@lickle/docs 0.0.0-dev.1

package/src/cli/vite/client/public/site.webmanifest

@@ -0,0 +1,21 @@
+{
+  "name": "lickle docs",
+  "short_name": "docs",
+  "icons": [
+    {
+      "src": "/web-app-manifest-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/web-app-manifest-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

package/src/cli/vite/index.ts

@@ -0,0 +1,115 @@
+import tailwindcss from '@tailwindcss/vite'
+import { fileURLToPath } from 'node:url'
+import solid from 'vite-plugin-solid'
+import * as vite from 'vite'
+import path from 'node:path'
+
+import * as config from '../../config/index.ts'
+import * as core from '../../core/index.ts'
+import * as lib from '../../_lib/index.ts'
+
+const JSON_ID = 'virtual:lickle/docs.json'
+const CUSTOM_ID = 'virtual:lickle/custom.ts'
+const viteRoot = fileURLToPath(new URL('./client', import.meta.url))
+const libRoot = fileURLToPath(new URL('../../../', import.meta.url))
+
+export interface DocsOptions extends config.ConfigJson {
+  build: () => Promise<core.project.ProjectJson>
+  entrypoint?: string | undefined
+  watchPaths?: string[]
+  viteConfig?: vite.InlineConfig
+}
+
+const resolveOptions = (opts: DocsOptions, mode: 'dev' | 'build') => {
+  const outDir = opts.custom ? path.join(path.dirname(opts.custom), 'dist') : 'docs/dist'
+  return {
+    root: viteRoot,
+    plugins: [solid(), tailwindcss(), docsPlugin(opts, mode)],
+    build: { outDir: outDir ? path.resolve(process.cwd(), outDir) : path.resolve(process.cwd(), 'docs/dist') },
+  }
+}
+
+export const dev = async (options: DocsOptions) => {
+  const server = await vite.createServer(resolveOptions(options, 'dev'))
+  await server.listen()
+  server.printUrls()
+  return server
+}
+
+export const build = async (options: DocsOptions) => vite.build(resolveOptions(options, 'build'))
+
+const docsPlugin = (opts: DocsOptions, mode: 'dev' | 'build'): vite.Plugin => {
+  let json: string | undefined
+  let logger: vite.Logger | undefined = undefined
+
+  const HMR_PATH = `/@virtual:${JSON_ID}`
+  const LIB_UI_PATH = path.resolve(libRoot, './src/ui/index.ts')
+  const LIB_THEME_CSS_PATH = path.resolve(libRoot, 'theme.css')
+  const LIB_SOLIDJS_PATH = path.resolve(libRoot, './src/solidjs/index.ts')
+
+  return {
+    name: 'docs',
+    enforce: 'pre',
+    configResolved(config) {
+      logger = config.logger
+    },
+    config: () => {
+      return {
+        resolve: {
+          alias: {
+            '@lickle/docs/ui': LIB_UI_PATH,
+            '@lickle/docs/theme.css': LIB_THEME_CSS_PATH,
+            '@lickle/docs/solidjs': LIB_SOLIDJS_PATH,
+          },
+        },
+        server: { fs: { allow: [viteRoot, opts.entrypoint ? path.dirname(opts.entrypoint) : viteRoot] } },
+      }
+    },
+
+    // transformIndexHtml: {
+    //   order: 'pre',
+    //   handler(html) {
+    //     return html.replace('<script type="module" src="./index.tsx"></script>', `<script type="module" src="${entrypoint}"></script>`)
+    //   },
+    // },
+
+    resolveId(id) {
+      if (id === JSON_ID || id === HMR_PATH) return '\0' + JSON_ID
+      if (id === CUSTOM_ID) return '\0' + CUSTOM_ID
+      return undefined
+    },
+
+    async load(id) {
+      if (id === '\0' + JSON_ID) {
+        if (mode === 'build') return JSON.stringify(await opts.build())
+        return json ?? 'null'
+      }
+      if (id === '\0' + CUSTOM_ID) return opts.entrypoint ? `import ${JSON.stringify(opts.entrypoint)}\n` : '\n'
+      return undefined
+    },
+
+    configureServer(s) {
+      if (!opts.build) return
+      const build = opts.build
+      const handleJson = async () => {
+        if (json) logger?.info('Rebuilding docs', { timestamp: true })
+        const nextJson = await build()
+        json = JSON.stringify(nextJson)
+        logger?.info('Docs built successfully', { timestamp: true })
+
+        const mod = s.moduleGraph.getModuleById('\0' + JSON_ID)
+        if (mod) {
+          s.moduleGraph.invalidateModule(mod)
+          s.ws.send({ type: 'custom', event: 'docs-update', data: nextJson })
+        }
+      }
+
+      const watchPaths = opts.watchPaths ?? []
+      watchPaths.forEach((p) => s.watcher.add(p))
+
+      const rebuild = lib.util.serial(() => handleJson())
+      s.watcher.on('change', (changedPath) => watchPaths.some((p) => changedPath.includes(p)) && rebuild())
+      rebuild()
+    },
+  }
+}

package/src/cli.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import { app } from './cli/index.ts'
+import { run } from 'cmd-ts'
+
+run(await app(), process.argv.slice(2))

package/src/config/defaults.ts

@@ -0,0 +1,36 @@
+import path from 'node:path'
+
+import type { ConfigJson } from './types.ts'
+
+import * as lib from '../_lib/index.ts'
+
+/**
+ * Resolve a partial `UserConfig` into a fully-defaulted `NewProjectConfig`.
+ *
+ * Missing fields fall back to `package.json`, conventional project files
+ * (`README.md`) and the working directory. `declarations` / `children` stay
+ * empty here — the reflection pass fills them once scanning is wired up.
+ */
+export const apply = async (dir: string, c?: Partial<ConfigJson>): Promise<ConfigJson> => {
+  const pkg = await lib.pkg.read(process.cwd())
+  const info = await lib.repo.info(dir)
+  const readme = await lib.fs.existingPath(path.join(dir, 'README.md'))
+  const defualtLinks = info ? [{ label: 'Repository', href: info.url }] : []
+  const entrypoints = c?.entrypoints ?? (await lib.pkg.resolveExportedSources(dir, pkg))
+  const tsconfig = lib.tsconfig.resolve(dir)
+
+  const name = c?.name ?? pkg?.name
+  if (!name) throw new Error('No project name found')
+
+  return {
+    ...c,
+    name,
+    version: c?.version ?? pkg?.version ?? info?.tag,
+    readme,
+    entrypoints,
+    links: c?.links ?? defualtLinks,
+    repository: info ? { url: info.url, rev: info.commit, fileUrl: info.fileUrl } : undefined,
+    srcDir: c?.srcDir ?? tsconfig.rootDir,
+    full: c?.full,
+  }
+}

package/src/config/file.ts

@@ -0,0 +1,53 @@
+import { pathToFileURL } from 'node:url'
+import { createJiti } from 'jiti'
+import fs from 'node:fs/promises'
+import { v } from '@lickle/is'
+import fg from 'fast-glob'
+
+import { type ConfigJson } from './types.ts'
+
+const EXT = ['ts', 'mts', 'cts', 'js', 'cjs', 'mjs', 'json']
+
+export const load = async (dir: string): Promise<ConfigJson | undefined> => {
+  const file = await find(dir)
+  if (!file) return undefined
+  if (file.endsWith('.json')) return readJson(file)
+  return readCode(file)
+}
+
+const find = async (dir: string): Promise<string | undefined> => {
+  const ext = EXT.join(',')
+  const files = await fg.glob(`lickle.{${ext}}`, { cwd: dir, absolute: true })
+  return files?.[0]
+}
+
+const readCode = async (file: string): Promise<ConfigJson> => {
+  const jti = createJiti(pathToFileURL(import.meta.url).href, {
+    moduleCache: false,
+    cache: false,
+  })
+  const mod = await jti.import<{ default: any }>(file)
+  const fl = await mod.default
+  return valid(fl)
+}
+
+const readJson = async (file: string): Promise<ConfigJson> => {
+  const content = await fs.readFile(file, 'utf-8')
+  const j = JSON.parse(content) as unknown
+  return valid(j)
+}
+
+const schema = v.struct({
+  name: v.string,
+  version: v.or(v.string, v.undefined),
+  readme: v.or(v.string, v.undefined),
+  links: v.or(v.array(v.struct({ label: v.string, href: v.string })), v.undefined),
+  tsconfig: v.or(v.string, v.undefined),
+  repository: v.or(v.struct({ url: v.string, rev: v.string, fileUrl: v.string }), v.undefined),
+  srcDir: v.or(v.string, v.undefined),
+  entrypoints: v.or(v.array(v.struct({ as: v.string, path: v.string })), v.undefined),
+  exclude: v.or(v.array(v.string), v.undefined),
+  full: v.or(v.boolean, v.undefined),
+})
+
+const valid = v.assert(schema)

package/src/config/index.ts

@@ -0,0 +1,11 @@
+import * as lib from '../_lib/index.ts'
+
+import type { ConfigJson } from './types.ts'
+export type * from './types.ts'
+
+export const defineConfig = <C extends ConfigJson | (() => ConfigJson) | (() => Promise<ConfigJson>)>(config: C) => {
+  const c = typeof config === 'function' ? config() : config
+  return Promise.resolve(c)
+}
+
+export const fromExports = async () => lib.pkg.resolveExportedSources(process.cwd(), await lib.pkg.read(process.cwd()))

package/src/config/load.ts

@@ -0,0 +1,95 @@
+import fs from 'node:fs/promises'
+import { v } from '@lickle/is'
+import path from 'node:path'
+import ts from 'typescript'
+import fg from 'fast-glob'
+
+import type * as project from '../core/project/index.ts'
+import * as lib from '../_lib/index.ts'
+
+import { type ConfigJson } from './types.ts'
+import * as defaults from './defaults.ts'
+import * as types from './types.ts'
+
+export type * from './types.ts'
+
+const EXT = ['ts', 'mts', 'cts', 'js', 'cjs', 'mjs', 'json']
+
+export const loadGen = async (dir: string = process.cwd(), opts?: Partial<types.ConfigJson>) => {
+  const c = await load(dir, opts)
+  return toGenerateOptions(c)
+}
+
+export const toGenerateOptions = async (c: ConfigJson & { compilerOptions: ts.CompilerOptions }) => {
+  const gen: project.GenerateOptions = {
+    dir: process.cwd(),
+    ...c,
+    exclude: c.exclude ?? [],
+    config: { entrypoints: [], links: [], ...c, routes: [] },
+    compilerOptions: c.compilerOptions,
+    full: c.full,
+  }
+
+  if (c.readme) {
+    const page: project.PageType<'markdown'> = {
+      kind: 'markdown',
+      content: await lib.fs.readFile(c.readme, 'utf-8'),
+    }
+    gen.config.routes = [{ label: 'README', slug: 'readme', page, children: [], sidebar: true }]
+  }
+
+  return gen
+}
+
+export const load = async (
+  dir: string = process.cwd(),
+  opts?: Partial<types.ConfigJson>,
+): Promise<types.ConfigJson & { compilerOptions: ts.CompilerOptions }> => {
+  const c = lib.tsconfig.resolve(dir)
+  if (!c.config) throw new Error('No tsconfig.json found')
+  const loaded = await loadFile(dir)
+  const info = await defaults.apply(dir, { ...loaded, ...opts })
+  const parsed = ts.parseJsonConfigFileContent(c.config, ts.sys, path.dirname(c.config.path))
+  return { ...info, compilerOptions: parsed.options }
+}
+
+const loadFile = async (dir: string): Promise<ConfigJson | undefined> => {
+  const file = await findFile(dir)
+  if (!file) return undefined
+  if (file.endsWith('.json')) return readJson(file)
+  return readCode(file)
+}
+
+export const findFile = async (dir: string): Promise<string | undefined> => {
+  const ext = EXT.join(',')
+  const files = await fg.glob(`lickle.{${ext}}`, { cwd: dir, absolute: true })
+  return files?.[0]
+}
+
+const readCode = async (file: string): Promise<ConfigJson> => {
+  const mod = await lib.jiti.importModule<{ default: any }>(file)
+  return valid(mod.default)
+}
+
+const readJson = async (file: string): Promise<ConfigJson> => {
+  const content = await fs.readFile(file, 'utf-8')
+  const j = JSON.parse(content) as unknown
+  return valid(j)
+}
+
+export const schema = v.struct({
+  name: v.string,
+  version: v.or(v.string, v.undefined),
+  readme: v.or(v.string, v.undefined),
+  links: v.or(v.array(v.struct({ label: v.string, href: v.string })), v.undefined),
+  tsconfig: v.or(v.string, v.undefined),
+  repository: v.or(v.struct({ url: v.string, rev: v.string, fileUrl: v.string }), v.undefined),
+  srcDir: v.or(v.string, v.undefined),
+  entrypoints: v.or(v.array(v.struct({ as: v.string, path: v.string })), v.undefined),
+  exclude: v.or(v.array(v.string), v.undefined),
+  full: v.or(v.boolean, v.undefined),
+})
+
+const valid = (c: unknown): ConfigJson => {
+  return c as ConfigJson
+}

package/src/config/types.ts

@@ -0,0 +1,59 @@
+/** Configuration used for generating the project json */
+export interface ConfigJson {
+  /** The name of the project. default is the package name from package.json */
+  name: string
+  /** The version of the project. default is the package version from package.json */
+  version?: string
+  /** README file path, default is README.md in the project root shown as home page */
+  readme?: string
+  /** Links for the project. defaults to package.json repository url */
+  links?: Link[]
+  /** tsconfig.json file path, default is tsconfig.json in the project root */
+  tsconfig?: string
+  /** Repository information */
+  repository?: Repo
+  /** Source directory, default to tsconfig.json `rootDir` or src */
+  srcDir?: string
+  /** Entrypoints — relative source paths reachable from `main` / `exports`. */
+  entrypoints?: Entry[]
+  /** Pages to include in the project. Default is the README file. */
+  pages?: Page[]
+  /** Custom  */
+  custom?: string
+  /** Files to exclude from the project (micromatch glob patterns) */
+  exclude?: string[]
+  /** Document every declaration, not just the exported public API. Default false. */
+  full?: boolean
+}
+
+export interface Page {
+  /** Page title */
+  title: string
+  /** Page path */
+  slug?: string
+  /** Page content */
+  content: string
+}
+
+export interface Entry {
+  /** Label used in the navigation */
+  as: string
+  /** File path or array of file paths, ['./src/index.ts'] */
+  path: string
+}
+
+export interface Link {
+  /** Label used in the navigation */
+  label: string
+  /** URL */
+  href: string
+}
+
+export interface Repo {
+  /** Repository URL */
+  url: string
+  /** Repository commit */
+  rev?: string
+  /** Repository file URL template with {PATH} {LINE} {COLUMN} to link to the source code */
+  fileUrl?: string
+}

package/src/core/index.ts

@@ -0,0 +1,2 @@
+export * as reflect from './reflect/index.ts'
+export * as project from './project/index.ts'

package/src/core/project/debug.ts

@@ -0,0 +1,30 @@
+import type { RouteNode } from './index.ts'
+
+export const displayRoutes = (routes: RouteNode[], prefix: string = '') => {
+  const kinds = { module: 'M', markdown: '.MD', declaration: 'D' }
+  // console.log(JSON.stringify(compact(routes)))
+
+  // routes.map
+  for (const r of routes) {
+    const id = (r.page as { id?: number }).id ?? r.label
+    console.log(`${prefix}${kinds[r.page.kind]} ${id} (${r.slug})`)
+    if (r.children) displayRoutes(r.children, prefix + '  ')
+  }
+}
+
+type CompactRouteNode = Pick<RouteNode, 'label' | 'slug'> & { children: CompactRouteNode[] }
+
+const compact = (routes: RouteNode[]): CompactRouteNode[] => {
+  return routes
+    .map((r) => {
+      // if (r.page.kind === 'declaration') return ['D']
+      return [
+        {
+          label: r.label,
+          slug: r.slug,
+          children: compact(r.children),
+        },
+      ]
+    })
+    .flat()
+}

package/src/core/project/index.ts

@@ -0,0 +1,58 @@
+import ts from 'typescript'
+import mm from 'micromatch'
+import path from 'node:path'
+
+import type { ProjectJson, RouteNode } from './types.ts'
+import * as reflect from '../reflect/index.ts'
+import * as routing from './routing.ts'
+
+export * from './debug.ts'
+export * from './types.ts'
+
+export type GenerateOptions = {
+  dir: string
+  exclude: string[]
+  config: Omit<ProjectJson, 'declarations'>
+  compilerOptions: ts.CompilerOptions
+  /** Override route naming / grouping / nav visibility. */
+  routeProvider?: routing.RouteProvider
+  /** Route every scanned declaration (incl. non-exported), not just the public API. */
+  full?: boolean
+}
+
+export const buildJson = async (opts: GenerateOptions): Promise<ProjectJson> => {
+  const graph = reflect.generate(opts.config.entrypoints, {
+    compilerOptions: opts.compilerOptions,
+    rootDir: opts.dir,
+    include: keepFile(opts),
+  })
+
+  const routes = Array.from(
+    routing.buildRoutes(graph, {
+      entrypoints: opts.config.entrypoints,
+      rootName: opts.config.name,
+      provider: opts.routeProvider,
+      mode: opts.full ? 'full' : 'exposed',
+      reserved: collectSlugs(opts.config.routes),
+    }),
+  )
+
+  return {
+    ...opts.config,
+    declarations: [...graph.declarations()],
+    routes: [...opts.config.routes, ...routes],
+  }
+}
+
+/** All slugs in a route subtree, so routing can avoid colliding with them. */
+const collectSlugs = (routes: RouteNode[]): string[] => routes.flatMap((r) => [r.slug, ...collectSlugs(r.children)])
+
+const keepFile =
+  (opts: GenerateOptions) =>
+  (sf: ts.SourceFile): boolean => {
+    if (sf.isDeclarationFile) return false
+    if (sf.fileName.includes('/node_modules/')) return false
+    const relative = path.relative(opts.dir, sf.fileName)
+    if (opts.exclude?.some((i) => mm.isMatch(relative, i))) return false
+    return true
+  }

package/src/core/project/naming.ts

@@ -0,0 +1,49 @@
+import * as path from '../../_lib/path/index.ts'
+import type * as reflect from '../reflect/index.ts'
+
+/** Display + URL identity for a route. */
+export type Parts = { label: string; slug: string; qualified: string }
+
+export type NameOptions = {
+  /** Project name, used as the label of the main entry module. */
+  rootName: string
+  /** Module path -> entrypoint alias (the `as` value without a leading `./`). */
+  aliases: Map<string, string>
+  /** Common directory prefix shared by every module path. */
+  commonDir: string
+}
+
+/**
+ * Parts for a root entry module — its slug is the site-relative base that all
+ * descendants build on. The main entry (`.`) lives at the root (`''`).
+ */
+export const rootParts = (d: reflect.Declaration<'module'>, opts: NameOptions): Parts => {
+  const alias = opts.aliases.get(d.path)
+  if (alias && alias !== '.') return { label: alias, slug: alias, qualified: alias }
+  const seg = moduleSegments(d.path, opts.commonDir)
+  if (seg.length === 0) return { label: opts.rootName, slug: '', qualified: opts.rootName }
+  const joined = seg.join('.')
+  return { label: joined, slug: seg.join('/'), qualified: joined }
+}
+
+/** Parts for a route nested under `parent`, named by its local `segment`. */
+export const childParts = (segment: string, parent: Parts): Parts => ({
+  label: segment,
+  slug: parent.slug ? `${parent.slug}/${segment}` : segment,
+  qualified: parent.qualified ? `${parent.qualified}.${segment}` : segment,
+})
+
+/**
+ * Module path -> path segments, relative to the common source dir, with the
+ * file extension dropped and a trailing `index` removed. Pure string ops, so
+ * no regex is built from (and broken by) arbitrary file paths.
+ */
+const moduleSegments = (modulePath: string, commonDir: string): string[] => {
+  let rel = modulePath
+  if (commonDir && rel.startsWith(commonDir)) rel = rel.slice(commonDir.length)
+  const segs = rel.split('/').filter(Boolean)
+  const last = segs[segs.length - 1]
+  if (last && /^index\./.test(last)) segs.pop()
+  else if (last) segs[segs.length - 1] = path.stripExt(last)
+  return segs
+}