Add configurable source link generation for documentation

- Introduce `srcLink` configuration option in schema and configuration
- Update CLI, Configuration, and Printer modules to support custom source links
- Implement fallback source link generation using project homepage
- Modify test cases to validate new source link configuration

Author: gcanti

docs/modules/Configuration.ts.md

@@ -39,6 +39,7 @@ Since v0.6.0
 declare const ConfigurationSchema: Schema.Struct<{
   $schema: Schema.optional<typeof Schema.String>
   projectHomepage: Schema.optional<typeof Schema.String>
+  srcLink: Schema.optional<typeof Schema.String>
   srcDir: Schema.optional<typeof Schema.String>
   outDir: Schema.optional<typeof Schema.String>
   theme: Schema.optional<typeof Schema.String>
@@ -66,6 +67,7 @@ Since v0.6.0
 export interface ConfigurationShape {
   readonly projectName: string
   readonly projectHomepage: string
+  readonly srcLink: string
   readonly srcDir: string
   readonly outDir: string
   readonly theme: string

schema.json

@@ -12,6 +12,10 @@
           "type": "string",
           "description": "Will link to the project homepage from the Auxiliary Links of the generated documentation."
         },
+        "srcLink": {
+          "type": "string",
+          "description": "Will link to the project source code."
+        },
         "srcDir": {
           "type": "string",
           "description": "The directory in which docgen will search for TypeScript files to parse.",
@@ -96,4 +100,4 @@
     }
   },
   "$ref": "#/$defs/ConfigurationSchema"
-}
+}

src/CLI.ts

@@ -27,6 +27,14 @@ const projectHomepage = Options.text("homepage").pipe(
   Options.optional
 )
 
+const srcLink = Options.text("srcLink").pipe(
+  Options.withFallbackConfig(Config.string("srcLink")),
+  Options.withDescription(
+    "The link to the project source code"
+  ),
+  Options.optional
+)
+
 const srcDir = Options.directory("src", { exists: "yes" }).pipe(
   Options.withFallbackConfig(Config.string("src").pipe(Config.withDefault("src"))),
   Options.withDescription(
@@ -157,6 +165,7 @@ const examplesCompilerOptions = Options.file("examples-tsconfig-file", { exists:
 
 const options = {
   projectHomepage,
+  srcLink,
   srcDir,
   outDir,
   theme,

src/Configuration.ts

@@ -35,6 +35,9 @@ export const ConfigurationSchema = Schema.Struct({
   projectHomepage: Schema.optional(Schema.String).annotations({
     description: "Will link to the project homepage from the Auxiliary Links of the generated documentation."
   }),
+  srcLink: Schema.optional(Schema.String).annotations({
+    description: "Will link to the project source code."
+  }),
   srcDir: Schema.optional(Schema.String).annotations({
     description: "The directory in which docgen will search for TypeScript files to parse.",
     default: "src"
@@ -85,6 +88,7 @@ export const ConfigurationSchema = Schema.Struct({
 export interface ConfigurationShape {
   readonly projectName: string
   readonly projectHomepage: string
+  readonly srcLink: string
   readonly srcDir: string
   readonly outDir: string
   readonly theme: string
@@ -225,6 +229,7 @@ const PackageJsonSchema = Schema.Struct({
 /** @internal */
 export const load = (args: {
   readonly projectHomepage: Option.Option<string>
+  readonly srcLink: Option.Option<string>
   readonly srcDir: string
   readonly outDir: string
   readonly theme: string
@@ -248,6 +253,7 @@ export const load = (args: {
     const packageJson = yield* validateJsonFile(PackageJsonSchema, packageJsonPath)
     const projectName = packageJson.name
     const projectHomepage = Option.getOrElse(args.projectHomepage, () => packageJson.homepage)
+    const srcLink = Option.getOrElse(args.srcLink, () => `${projectHomepage}/blob/main/src/`)
 
     // Read the `docgen.json` configuration file to gain access to the TypeScript
     // configuration options
@@ -292,6 +298,7 @@ export const load = (args: {
       outDir,
       projectName,
       projectHomepage,
+      srcLink,
       exclude,
       examplesCompilerOptions,
       parseCompilerOptions

src/Printer.ts

@@ -117,7 +117,7 @@ const printOptionalSourceLink = (position?: Domain.Position) => {
     const config = yield* Configuration.Configuration
     const source = yield* Parser.Source
     const name = source.sourceFile.getBaseName()
-    return `\n\n[Source](${config.projectHomepage}/blob/main/src/${name}#L${position.line})`
+    return `\n\n[Source](${config.srcLink}${name}#L${position.line})`
   })
 }
 

test/Configuration.test.ts

@@ -15,11 +15,11 @@ import * as Option from "effect/Option"
 import * as assert from "node:assert/strict"
 import { describe, it } from "vitest"
 
-type DocgenJson = Record<string, unknown>
+type DocgenJson = typeof Configuration.ConfigurationSchema.Type
 
 class DocgenJsonTag extends Context.Tag("DocgenJsonTag")<DocgenJsonTag, DocgenJson>() {}
 
-const makeDocgenJson = (config: Record<string, unknown>) => Layer.succeed(DocgenJsonTag, config)
+const makeDocgenJson = (config: DocgenJson) => Layer.succeed(DocgenJsonTag, config)
 
 const TestFileSystem = Layer.effect(
   FileSystem.FileSystem,
@@ -79,6 +79,7 @@ describe("Configuration", () => {
       assert.deepStrictEqual(config, {
         projectName: "name",
         projectHomepage: "homepage",
+        srcLink: "homepage/blob/main/src/",
         srcDir: "src",
         outDir: "docs",
         theme: "mikearnaldi/just-the-docs",
@@ -114,6 +115,7 @@ describe("Configuration", () => {
       assert.deepStrictEqual(config, {
         projectName: "name",
         projectHomepage: "myproject",
+        srcLink: "mygithub",
         srcDir: "src",
         outDir: "docs",
         theme: "mikearnaldi/just-the-docs",
@@ -132,6 +134,7 @@ describe("Configuration", () => {
       Effect.provide(TestLive.pipe(Layer.provide(
         makeDocgenJson({
           projectHomepage: "myproject",
+          srcLink: "mygithub",
           parseCompilerOptions
         })
       ))),
@@ -142,7 +145,7 @@ describe("Configuration", () => {
   it("should raise a validation error if docgen.json is not valid", async () => {
     const cli = testCliFor(Effect.void)
     const result = await cli([]).pipe(
-      Effect.provide(TestLive.pipe(Layer.provide(makeDocgenJson({ projectHomepage: 1 })))),
+      Effect.provide(TestLive.pipe(Layer.provide(makeDocgenJson({ projectHomepage: 1 } as any)))),
       Effect.runPromiseExit
     )
     assert.deepStrictEqual(

test/Parser.test.ts

@@ -18,6 +18,7 @@ const project = new ast.Project({
 const defaultConfig: Configuration.ConfigurationShape = {
   projectName: "docgen",
   projectHomepage: "https://github.com/effect-ts/docgen",
+  srcLink: "https://github.com/effect-ts/docgen/blob/main/src/",
   srcDir: "src",
   outDir: "docs",
   theme: "pmarsceill/just-the-docs",