@lickle/docs 0.0.0-dev.1

package/src/_lib/path/index.ts

@@ -0,0 +1,44 @@
+export const common = (pths: string[]): string => {
+  if (pths.length === 0) return ''
+
+  const split = pths.map((p) => p.split('/'))
+  const first = split[0]!
+  let i = 0
+  for (; i < first.length; i++) {
+    if (!split.every((parts) => parts[i] === first[i])) break
+  }
+  return first.slice(0, i).join('/')
+}
+
+export const slugMaker = () => {
+  const used = new Set<string>()
+  return {
+    uniq: (sl: string) => uniqueSlug(sl, used),
+    add: (sl: string) => {
+      if (used.has(sl)) throw new Error(`Duplicate slug: ${sl}`)
+      used.add(sl)
+    },
+  }
+}
+
+export const make = slugMaker()
+
+export const stripExt = (s: string): string => s.replace(/\.[^./]+$/, '')
+
+export const toSlug = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9.]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+const uniqueSlug = (base: string, used: Set<string>): string => {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let n = 2
+  while (used.has(`${base}-${n}`)) n++
+  const slug = `${base}-${n}`
+  used.add(slug)
+  return slug
+}

package/src/_lib/pkg/index.ts

@@ -0,0 +1,165 @@
+import { exports as resolveExports, type Package } from 'resolve.exports'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+import * as tsconfig from '../tsconfig/index.ts'
+import { memo1 } from '../util/index.ts'
+
+export interface PackageJson extends Package {
+  repository?: { type: string; url: string; directory?: string } | string
+}
+
+export const read = memo1(async (projectDir: string) => {
+  const pkg = JSON.parse(await fs.readFile(path.join(projectDir, 'package.json'), 'utf8'))
+  return pkg as PackageJson
+})
+
+export type ExportedSource = { path: string; as: string }
+
+interface Options {
+  /** Resolve "require"/"node" conditions instead of "import". @default false */
+  require?: boolean
+  /** Extra user conditions to match (e.g. "development"). */
+  conditions?: readonly string[]
+}
+
+/**
+ * Returns the source files corresponding to a package's published entry points,
+ * resolving `exports` (with conditions/wildcards) or `main`, mapping each emitted
+ * file back to its source via `.d.ts.map`/`.js.map` source maps when available,
+ * and otherwise via the tsconfig `outDir`/`rootDir` swap.
+ */
+export const resolveExportedSources = async (
+  projectDir: string,
+  pkg: PackageJson,
+  options: Options = {},
+): Promise<ExportedSource[]> => {
+  // --- 1. enumerate (subpath -> dist file) -------------------------------
+  const entries: { as: string; dist: string }[] = []
+
+  if (pkg.exports != null) {
+    for (const subpath of listExportSubpaths(pkg.exports)) {
+      // resolve.exports applies condition + wildcard logic for this subpath.
+      const resolved = resolveExports(pkg, subpath, {
+        require: options.require,
+        conditions: options.conditions,
+      })
+      const dist = resolved?.[0]
+      if (dist) entries.push({ as: subpath, dist })
+    }
+  } else if (typeof pkg.main === 'string') {
+    entries.push({ as: '.', dist: pkg.main })
+  } else if (typeof pkg.module === 'string') {
+    entries.push({ as: '.', dist: pkg.module })
+  }
+
+  // --- 2. tsconfig fallback paths ----------------------------------------
+  const { outDir, rootDir } = tsconfig.resolve(projectDir)
+
+  // --- 3. dist -> source --------------------------------------------------
+  const results: ExportedSource[] = []
+  const seen = new Set<string>()
+
+  for (const { as, dist } of entries) {
+    const distAbs = path.resolve(projectDir, dist)
+    const src =
+      (await resolveViaSourceMap(distAbs, projectDir)) ??
+      (await resolveViaTsconfig(distAbs, projectDir, outDir, rootDir))
+    if (!src) continue
+
+    const key = `${as}\0${src}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    results.push({ as, path: src })
+  }
+
+  return results
+}
+
+// --- exports enumeration --------------------------------------------------
+
+/** List the subpath keys of an `exports` field (".", "./foo", ...). */
+const listExportSubpaths = (exportsField: unknown): string[] => {
+  if (typeof exportsField === 'string') return ['.']
+  if (exportsField == null || typeof exportsField !== 'object') return []
+
+  const keys = Object.keys(exportsField as Record<string, unknown>)
+  const subpathKeys = keys.filter((k) => k === '.' || k.startsWith('./'))
+
+  // If no subpath-style keys, the object is a bare conditions map for ".".
+  return subpathKeys.length > 0 ? subpathKeys : ['.']
+}
+
+// --- dist -> source: source maps -----------------------------------------
+
+const resolveViaSourceMap = async (distAbs: string, projectDir: string): Promise<string | null> => {
+  // Prefer the declaration map, then the js map.
+  const mapCandidates = [
+    distAbs.replace(/\.d\.ts$/, '.d.ts.map'),
+    distAbs + '.map',
+    distAbs.replace(/\.(js|mjs|cjs|jsx)$/, (m) => m + '.map'),
+  ]
+
+  for (const mapPath of mapCandidates) {
+    let raw: string
+    try {
+      raw = await fs.readFile(mapPath, 'utf8')
+    } catch {
+      continue
+    }
+
+    let map: { sources?: string[]; sourceRoot?: string }
+    try {
+      map = JSON.parse(raw)
+    } catch {
+      continue
+    }
+
+    const first = map.sources?.[0]
+    if (!first) continue
+
+    const sourceAbs = path.resolve(path.dirname(mapPath), map.sourceRoot ?? '', first)
+    return toPosixRelative(projectDir, sourceAbs)
+  }
+
+  return null
+}
+
+// --- dist -> source: tsconfig outDir/rootDir swap ------------------------
+
+const resolveViaTsconfig = async (
+  distAbs: string,
+  projectDir: string,
+  outDir: string,
+  rootDir: string,
+): Promise<string | null> => {
+  const rel = path.relative(outDir, distAbs)
+  if (rel.startsWith('..')) return null
+
+  const base = rel.replace(/\.d\.ts$/, '').replace(/\.(js|mjs|cjs|jsx)$/, '')
+  const candidateBase = path.join(rootDir, base)
+
+  for (const ext of ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx']) {
+    for (const candidate of [candidateBase + ext, path.join(candidateBase, 'index' + ext)]) {
+      if (await exists(candidate)) {
+        return toPosixRelative(projectDir, candidate)
+      }
+    }
+  }
+  return null
+}
+
+// --- helpers --------------------------------------------------------------
+
+function toPosixRelative(from: string, to: string): string {
+  return path.relative(from, to).split(path.sep).join('/')
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/_lib/repo/index.ts

@@ -0,0 +1,138 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+import hostedGitInfo from 'hosted-git-info'
+import * as pkg from '../pkg/index.ts'
+
+const exec = promisify(execFile)
+
+export interface RepoInfo {
+  /** Clean browseable web URL, e.g. https://github.com/user/repo */
+  url: string
+  /** Web URL pointing at the package's subdirectory, if `directory` is set. */
+  directoryUrl?: string
+  /** Normalized git clone URL, e.g. git+https://github.com/user/repo.git */
+  git: string
+  /** Host shortcut, e.g. github:user/repo */
+  shortcut: string
+  host: string // "github.com", "gitlab.com", ...
+  user: string
+  project: string
+  /** Short commit hash of HEAD, if inside a git work tree. */
+  commit?: string
+  /** Nearest tag describing HEAD (e.g. "v1.2.0" or "v1.2.0-3-gabc123"). */
+  tag?: string
+  /** Web URL pinned to the resolved commit, if available. */
+  commitUrl?: string
+  /** Web URL pinned to the resolved commit, if available. */
+  fileUrl?: string
+  /** Where the URL came from. */
+  source: 'package.json' | 'git'
+}
+
+/**
+ * Resolve a project's repository URL.
+ * Reads package.json `repository` (string or object, including monorepo
+ * `directory`), falling back to the local git `origin` remote.
+ */
+export const info = async (projectDir: string): Promise<RepoInfo | null> => {
+  const rev = await getGitRevision(projectDir)
+  const fromPkg = await fromPackageJson(projectDir, rev)
+  if (fromPkg) return fromPkg
+  return fromGit(projectDir, rev)
+}
+
+type GitRevision = { commit?: string; tag?: string }
+
+async function getGitRevision(projectDir: string): Promise<GitRevision> {
+  const commit = await gitOut(projectDir, ['rev-parse', '--short', 'HEAD'])
+  const described = await gitOut(projectDir, ['describe', '--tags', '--always'])
+  const tag = described && described !== commit ? described : undefined
+  return { commit: commit || undefined, tag }
+}
+
+async function gitOut(cwd: string, args: string[]): Promise<string | null> {
+  try {
+    const { stdout } = await exec('git', args, { cwd })
+    return stdout.trim()
+  } catch {
+    return null
+  }
+}
+
+async function fromPackageJson(projectDir: string, rev: GitRevision): Promise<RepoInfo | null> {
+  let pk: pkg.PackageJson
+  try {
+    pk = await pkg.read(projectDir)
+  } catch {
+    return null
+  }
+
+  const repo = pk.repository
+  if (repo == null) return null
+
+  const rawUrl = typeof repo === 'string' ? repo : repo.url
+  const directory = typeof repo === 'object' ? repo.directory : undefined
+  if (typeof rawUrl !== 'string') return null
+
+  const info = hostedGitInfo.fromUrl(rawUrl)
+  if (!info) {
+    // Unrecognized host: return the raw url, best-effort.
+    return {
+      url: rawUrl.replace(/^git\+/, '').replace(/\.git$/, ''),
+      git: rawUrl,
+      shortcut: rawUrl,
+      host: '',
+      user: '',
+      project: '',
+      commit: rev.commit,
+      tag: rev.tag,
+      source: 'package.json',
+    }
+  }
+
+  return build(info, directory, rev, 'package.json')
+}
+
+async function fromGit(projectDir: string, rev: GitRevision): Promise<RepoInfo | null> {
+  const origin = await gitOut(projectDir, ['config', '--get', 'remote.origin.url'])
+  if (!origin) return null
+
+  const info = hostedGitInfo.fromUrl(origin)
+  if (!info) return null
+  return build(info, undefined, rev, 'git')
+}
+
+function build(
+  info: hostedGitInfo,
+  directory: string | undefined,
+  rev: GitRevision,
+  source: RepoInfo['source'],
+): RepoInfo {
+  const url = info.browse()
+  // Pin to the commit: `${repo}/tree/${commit}[/${directory}]`. This layout is
+  // shared by GitHub, GitLab, and Bitbucket; browse()'s committish arg is only
+  // a URL fragment in this version, so we construct it explicitly.
+  const commitUrl = rev.commit
+    ? `${url}/tree/${rev.commit}${directory ? '/' + directory.replace(/^\/+/, '') : ''}`
+    : undefined
+
+  const fileUrl = rev.commit
+    ? `${url}/blob/${rev.commit}${directory ? '/' + directory.replace(/^\/+/, '') : ''}{PATH}#L{LINE}`
+    : undefined
+
+  return {
+    url,
+    directoryUrl: directory ? info.browse(directory) : undefined,
+    git: info.https(),
+    shortcut: info.shortcut(),
+    host: info.domain,
+    user: info.user,
+    project: info.project,
+    commit: rev.commit,
+    tag: rev.tag,
+    commitUrl,
+    fileUrl,
+    source,
+  }
+}

package/src/_lib/slug/index.ts

@@ -0,0 +1,26 @@
+const slugBuilder = () => {
+  const used = new Set<string>()
+  return (sl: string) => uniqueSlug(toSlug(sl), used)
+}
+
+export const make = slugBuilder()
+
+export const stripExt = (s: string): string => s.replace(/\.[^./]+$/, '')
+
+export const toSlug = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9.]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+const uniqueSlug = (base: string, used: Set<string>): string => {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let n = 2
+  while (used.has(`${base}-${n}`)) n++
+  const slug = `${base}-${n}`
+  used.add(slug)
+  return slug
+}

package/src/_lib/t.ts

@@ -0,0 +1,17 @@
+export type MapKind<
+  Map extends Record<string, any>,
+  Key extends string = 'kind',
+  Extra extends Record<string, any> = {},
+> = {
+  [K in keyof Map]: Compute<Map[K] & Extra & { [_K in Key]: K }>
+}
+
+export type MapKindUnion<
+  Map extends Record<string, any>,
+  Key extends string = 'kind',
+  Extra extends Record<string, any> = {},
+> = MapKind<Map, Key, Extra>[keyof Map]
+
+export type Compute<T> = { [K in keyof T]: T[K] } & {}
+
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never

package/src/_lib/tsconfig/index.ts

@@ -0,0 +1,20 @@
+import { getTsconfig, type TsConfigResult } from 'get-tsconfig'
+import path from 'node:path'
+
+import { memo1 } from '../util/index.ts'
+
+export type ResolvedTsconfig = {
+  config: TsConfigResult | null
+  outDir: string
+  rootDir: string
+}
+
+export const resolve = memo1((projectDir: string): ResolvedTsconfig => {
+  const tsconfigResult = getTsconfig(projectDir) // resolves `extends`, JSONC, etc.
+  const opts = tsconfigResult?.config.compilerOptions ?? {}
+  const tsconfigDir = tsconfigResult ? path.dirname(tsconfigResult.path) : projectDir
+  const outDir = path.resolve(tsconfigDir, opts.outDir ?? 'dist')
+  const rootDir = path.resolve(tsconfigDir, opts.rootDir ?? 'src')
+
+  return { outDir, rootDir, config: tsconfigResult }
+})

package/src/_lib/util/index.ts

@@ -0,0 +1,53 @@
+type Fn = (...args: any[]) => any
+export const memo = <F extends Fn>(fn: F): F => {
+  const cache = new Map<string, ReturnType<F>>()
+  return ((...args: any[]) => {
+    const key = JSON.stringify(args)
+    if (cache.has(key)) return cache.get(key)!
+    const result = fn(...args)
+    cache.set(key, result)
+    return result
+  }) as F
+}
+
+/** Cache on the first argument */
+export const memo1 = <F extends Fn>(fn: F): F => {
+  const cache = new Map<any, ReturnType<F>>()
+  return ((...args: any[]) => {
+    const key = args[0]
+    if (cache.has(key)) return cache.get(key)!
+    const result = fn(...args)
+    cache.set(key, result)
+    return result
+  }) as F
+}
+
+/** Serialise overlapping async invocations; if a call arrives mid-run, replay once. */
+export const serial = (fn: () => Promise<any>) => {
+  let busy = false
+  let queued = false
+  const run = async (): Promise<void> => {
+    if (busy) return void (queued = true)
+    busy = true
+    try {
+      await fn()
+    } catch (e) {
+      console.error('[build]', e)
+    }
+    busy = false
+    if (queued) {
+      queued = false
+      await run()
+    }
+  }
+  return run
+}
+
+export const registerNodeCleanup = (fn: () => any) => {
+  const cleanup = async () => {
+    await fn()
+    process.exit(0)
+  }
+  process.on('SIGINT', cleanup)
+  process.on('SIGTERM', cleanup)
+}

package/src/cli/cmd/dev.ts

@@ -0,0 +1,86 @@
+import * as cmd from 'cmd-ts'
+import path from 'node:path'
+
+import * as config from '../../config/load.ts'
+import * as core from '../../core/index.ts'
+import * as lib from '../../_lib/index.ts'
+import * as vite from '../vite/index.ts'
+import { getRootPath } from '../env.ts'
+
+export const dev = cmd.command({
+  name: 'dev',
+  description: 'Start a local dev server that rebuilds and live-reloads the docs on change',
+  args: {
+    docsDir: cmd.option({
+      long: 'docs-dir',
+      short: 'd',
+      type: cmd.optional(cmd.string),
+      description: 'Directory containing the docs sources (defaults to the configured srcDir)',
+    }),
+    port: cmd.option({
+      long: 'port',
+      short: 'p',
+      type: cmd.optional(cmd.number),
+      description: 'Port the dev server listens on (defaults to Vite\u2019s next free port)',
+    }),
+  },
+  handler: (args) => runDev(args),
+})
+
+export const build = cmd.command({
+  name: 'build',
+  description: 'Build the static documentation site into the output directory',
+  args: {
+    docsDir: cmd.option({
+      long: 'docs-dir',
+      short: 'd',
+      type: cmd.optional(cmd.string),
+      description: 'Directory containing the docs sources (defaults to the configured srcDir)',
+    }),
+  },
+  handler: (args) => runBuild(args),
+})
+
+type Options = {
+  docsDir?: string
+  port?: number
+}
+
+const runDev = async (opts: Options) => {
+  let watchList: string[] = []
+  const configFile = await config.findFile(process.cwd())
+  if (configFile) watchList.push(configFile)
+
+  const c = await config.load()
+  if (c.srcDir) watchList.push(c.srcDir)
+  watchList.push(getRootPath('src/core'))
+
+  const server = await vite.dev({
+    ...c,
+    build: async () =>
+      lib.jiti
+        .importModule<typeof core>(getRootPath('src/core'))
+        .then(async (core) => core.project.buildJson(await config.loadGen(process.cwd()))),
+    watchPaths: [...watchList],
+    entrypoint: c.custom ? path.join(process.cwd(), c.custom) : undefined,
+    viteConfig: {
+      server: { port: opts.port },
+    },
+  })
+
+  lib.util.registerNodeCleanup(async () => await server.close())
+}
+
+export const runBuild = async (opts: Options = {}) => {
+  const c = await config.load(opts.docsDir ?? process.cwd())
+  const json = await core.project.buildJson(await config.toGenerateOptions(c))
+
+  await vite.build({
+    ...c,
+    build: async () => json,
+    entrypoint: c.custom ? path.join(process.cwd(), c.custom) : undefined,
+    viteConfig: {
+      build: { outDir: c.custom ? path.join(path.dirname(c.custom), 'dist') : 'docs/dist' },
+    },
+  })
+}

package/src/cli/cmd/index.ts

@@ -0,0 +1,3 @@
+export * from './dev.ts'
+export * from './init.ts'
+export * from './json.ts'

package/src/cli/cmd/init.ts

@@ -0,0 +1,80 @@
+import * as cmd from 'cmd-ts'
+import path from 'node:path'
+
+import * as lib from '../../_lib/index.ts'
+
+export const init = cmd.command({
+  name: 'init',
+  description: 'Scaffold a config file and docs directory with a custom-component example',
+  args: {
+    dir: cmd.option({
+      long: 'dir',
+      short: 'd',
+      type: cmd.optional(cmd.string),
+      description: 'Directory to create the docs scaffold in (defaults to ./docs)',
+    }),
+    file: cmd.option({
+      long: 'config',
+      short: 'c',
+      type: cmd.optional(cmd.string),
+      defaultValue: () => path.join(process.cwd(), 'lickle.ts'),
+      description: 'Path to write the configuration file to (defaults to ./lickle.ts)',
+    }),
+    force: cmd.flag({
+      long: 'force',
+      short: 'f',
+      description: 'Overwrite existing scaffold files instead of skipping them',
+    }),
+  },
+  handler: async (args) => {
+    const file = args.file ?? path.join(process.cwd(), 'lickle.ts')
+    const dir = args.dir ?? path.join(process.cwd(), 'docs')
+
+    await lib.fs.ensureDir(file)
+    await lib.fs.writeFile(file, configTemplate)
+
+    await lib.fs.ensureDir(dir)
+    await writeInitFiles(dir, args.force)
+  },
+})
+
+const configTemplate = `
+import { defineConfig } from '@lickle/docs/config'
+
+export default defineConfig({
+  name: '@lickle/docs',
+  pages: [{ title: 'Overview', content: './README.md' }],
+  custom: './docs/index.tsx',
+})
+`
+
+const example = `
+import { registerComponent, LiveExample, transform } from '@lickle/docs/ui'
+
+// Execute the compiled example into its preview host. \`host\` is the live DOM
+// node, available to the example as a global.
+const run = (code: string, host: HTMLElement) => new Function('host', code)(host)
+
+// Opt in to runnable \`@example\` blocks: compile with \`transform\` then \`run\`.
+registerComponent('tag.example', (props) => (
+  <LiveExample {...props} run={(code, host) => run(transform(code), host)} />
+))`
+
+const initFiles = {
+  '.gitignore': [`docs.json`, `dist`],
+  'index.tsx': [example.trim()],
+  'tsconfig.json': [`{`, `  "extends": "@lickle/docs/tsconfig/tsconfig.client.json",`, `  "include": ["*"],`, `}`],
+}
+const writeInitFiles = async (dir: string, force: boolean = false) => {
+  for (const [file, content] of Object.entries(initFiles)) {
+    if (force) {
+      await lib.fs.writeFile(path.join(dir, file), content.join('\n'))
+      continue
+    }
+    if (await lib.fs.exists(path.join(dir, file))) {
+      console.log(`skipping ${file} as it already exists`)
+      continue
+    }
+    await lib.fs.writeFile(path.join(dir, file), content.join('\n'))
+  }
+}

package/src/cli/cmd/json.ts

@@ -0,0 +1,28 @@
+import * as cmd from 'cmd-ts'
+
+import * as project from '../../core/project/index.ts'
+import * as config from '../../config/load.ts'
+import * as core from '../../core/index.ts'
+import * as lib from '../../_lib/index.ts'
+
+export const json = cmd.command({
+  name: 'json',
+  description: 'Generate the project\u2019s JSON reflection data into the docs directory',
+  args: {
+    print: cmd.flag({
+      long: 'print',
+      short: 'p',
+      description: 'Print the generated route tree to the console',
+    }),
+    full: cmd.flag({
+      long: 'full',
+      description: 'Document every declaration, not just the exported public API',
+    }),
+  },
+  handler: async (args) => {
+    await lib.fs.ensureDir('docs')
+    const p = await core.project.buildJson(await config.loadGen(process.cwd(), { full: args.full }))
+    if (args.print) project.displayRoutes(p.routes)
+    await lib.fs.writeFile('docs/project.json', JSON.stringify(p, null, 2))
+  },
+})

package/src/cli/env.ts

@@ -0,0 +1,6 @@
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const libRoot = fileURLToPath(new URL('../../', import.meta.url))
+
+export const getRootPath = (pth?: string) => (pth ? path.resolve(libRoot, pth) : libRoot)

package/src/cli/index.ts

@@ -0,0 +1,14 @@
+import * as cmd from 'cmd-ts'
+
+import * as cmds from './cmd/index.ts'
+import * as lib from '../_lib/index.ts'
+
+export const app = async () => {
+  const version = await lib.pkg.read(process.cwd())
+  return cmd.subcommands({
+    name: 'ldocs',
+    version: version.version,
+    description: 'Generate documentation sites from TypeScript projects',
+    cmds: { json: cmds.json, dev: cmds.dev, build: cmds.build, init: cmds.init },
+  })
+}