@lickle/docs 0.0.0-dev.1

package/src/core/reflect/state.ts

@@ -0,0 +1,75 @@
+import ts from 'typescript'
+import path from 'path'
+
+import type * as T from './types.ts'
+
+/** How a given `exports` clause should populate its targets at resolve time. */
+export type ExportsForm = 'named-local' | 'named-from' | 'star' | 'namespace-from' | 'assignment'
+
+export interface ScanOptions {
+  rootDir: string
+  /** The compiler options for the project. */
+  compilerOptions: ts.CompilerOptions
+  /** Whether to include a file in the scan. */
+  include: (sf: ts.SourceFile) => boolean
+}
+
+export interface ScanState extends ScanOptions {
+  /** Monotonic id source. Every node that needs identity calls this. */
+  nextId: () => number
+  getPath: (sf: ts.SourceFile) => string
+  root: number
+  parent: number
+  currentStmt: number
+
+  checker: ts.TypeChecker
+  references: T.Type<'reference'>[]
+  exports: T.Declaration<'export'>[]
+  declarations: T.Declaration[]
+  symbolsById: Map<number, ts.Symbol>
+  referenceOrigins: Map<number, ts.Node>
+  /** Symbol for inferred references, which have no syntactic origin to re-resolve. */
+  referenceSymbols: Map<number, ts.Symbol>
+
+  // ---- deferred export population ----
+  /** exports id -> which population strategy resolve should use. */
+  exportsForm: Map<number, ExportsForm>
+  /** exports id -> source module specifier text, for the `*-from` forms. */
+  exportsSpec: Map<number, string>
+  /** exports id -> raw `{ name, as? }` entries, for the `named-*` forms. */
+  exportsEntries: Map<number, { name: string; as?: string }[]>
+  /** exports id -> alias, for `export * as <alias> from '…'`. */
+  exportsAlias: Map<number, string>
+  /** exports id -> origin node, so resolve can re-ask the checker. */
+  exportsOrigin: Map<number, ts.ExportDeclaration | ts.ExportAssignment>
+
+  /** Source files already scanned — dedups the transitive re-export worklist. */
+  seen: Set<ts.SourceFile>
+}
+
+export const makeScanState = (checker: ts.TypeChecker, options: ScanOptions): ScanState => {
+  const relPath = new WeakMap<ts.SourceFile, string>()
+  let id = 0
+  const getPath = (sf: ts.SourceFile) => relPath.get(sf) ?? path.relative(options.rootDir, sf.fileName)
+  return {
+    ...options,
+    root: 0,
+    parent: 0,
+    currentStmt: 0,
+    checker,
+    nextId: () => ++id,
+    getPath,
+    references: [],
+    exports: [],
+    declarations: [],
+    symbolsById: new Map(),
+    referenceOrigins: new Map(),
+    referenceSymbols: new Map(),
+    exportsForm: new Map(),
+    exportsSpec: new Map(),
+    exportsEntries: new Map(),
+    exportsAlias: new Map(),
+    exportsOrigin: new Map(),
+    seen: new Set(),
+  }
+}

package/src/core/reflect/types.ts

@@ -0,0 +1,164 @@
+import { is } from '@lickle/is'
+
+import type { t } from '../../_lib/index.ts'
+
+export type Source = { file: string; line: number; column: number }
+export type Typebase = { parent: number; comment?: Comment; sources: Source[] }
+export type Base = Typebase & { id: number; name: string; exported: boolean }
+
+export interface DeclerationDefinitions {
+  variable: { type: Type; defaultValue?: string }
+  function: { signatures: Part<'signature'>[] }
+  class: {
+    generics?: Part<'generic'>[]
+    extends?: Type[]
+    implements?: Type[]
+    constructors: Part<'signature'>[]
+    properties: Part<'property'>[]
+    methods: Part<'method'>[]
+    indexSignature?: Part<'index-signature'>
+  }
+  interface: {
+    generics?: Part<'generic'>[]
+    extends?: Type[]
+    properties: Part<'property'>[]
+    methods: Part<'method'>[]
+    callSignatures?: Part<'signature'>[]
+    constructSignatures?: Part<'signature'>[]
+    indexSignature?: Part<'index-signature'>
+  }
+  'type-alias': { generics?: Part<'generic'>[]; type: Type }
+  export: { names: { name: string; ref: number }[]; star: boolean }
+  enum: { const?: boolean; members: Part<'enum-member'>[] }
+  namespace: {}
+  module: { path: string }
+}
+
+export type ReferenceTypeMap = t.MapKind<
+  {
+    internal: { targetId: number }
+    external: { external: 'stdlib' | 'package' | 'anonymous' | 'type-parameter' }
+  },
+  'type'
+>
+
+export interface TypeDefinitions {
+  intrinsic: { name: IntrinsicName }
+  literal: { value: string | number | boolean | bigint | null }
+  reference: { id: number; name: string; owner: number; args?: Type[] } & ReferenceTypeMap[keyof ReferenceTypeMap]
+  union: { types: Type[] }
+  intersection: { types: Type[] }
+  array: { elementType: Type }
+  tuple: { elements: Part<'tuple-element'>[] }
+  'function-type': { signatures: Part<'signature'>[] }
+  'type-operator': { operator: 'keyof' | 'readonly' | 'unique'; target: Type }
+  /** Inline object type, e.g. `{ x: number; f(): void }`. */
+  record: {
+    properties: Part<'property'>[]
+    methods: Part<'method'>[]
+    callSignatures?: Part<'signature'>[]
+    constructSignatures?: Part<'signature'>[]
+    indexSignature?: Part<'index-signature'>
+  }
+  conditional: { check: Type; extends: Type; true: Type; false: Type }
+  infer: { name: string; constraint?: Type }
+  'indexed-access': { object: Type; index: Type }
+  mapped: { typeParameter: Part<'generic'>; nameType?: Type; type?: Type; optional?: boolean; readonly?: boolean }
+  query: { name: string; args?: Type[] }
+  'template-literal': { head: string; spans: { type: Type; literal: string }[] }
+  predicate: { parameter: string; asserts?: boolean; type?: Type }
+  'import-type': { argument: string; qualifier?: string; isTypeOf?: boolean; args?: Type[] }
+  unknown: { text: string; nodeType: string }
+}
+
+export interface TypeComponentDefinitions {
+  signature: { generics?: Part<'generic'>[]; params: Part<'parameter'>[]; return: Type }
+  parameter: { name: string; type: Type; rest?: boolean; default?: string; optional: boolean }
+  generic: { name: string; constraint?: Type; default?: Type }
+  property: { name: string; type: Type; defaultValue?: string; optional?: boolean }
+  method: { name: string; signatures: Part<'signature'>[] }
+  'index-signature': { parameter: Part<'parameter'>; type: Type }
+  'enum-member': { name: string; value?: string | number }
+  'tuple-element': { name?: string; type: Type; optional?: boolean; rest?: boolean }
+}
+
+export type IntrinsicName =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'bigint'
+  | 'symbol'
+  | 'void'
+  | 'undefined'
+  | 'null'
+  | 'never'
+  | 'any'
+  | 'unknown'
+  | 'object'
+  | 'this'
+
+// export type Reference = TypeMap['reference']
+
+export type Declaration<K extends keyof DeclarationMap = keyof DeclarationMap> = DeclarationMap[K]
+export type Type<K extends keyof TypeMap = keyof TypeMap> = TypeMap[K]
+export type Part<K extends keyof PartMap = keyof PartMap> = PartMap[K]
+export type Any<K extends keyof KindsMap = keyof KindsMap> = KindsMap[K]
+
+// ---------------- Guards ----------------
+// prettier-ignore
+const ISD = is.struct({ kind: is.oneOf('variable', 'function', 'class', 'interface', 'type-alias', 'export', 'enum', 'namespace', 'module') }, false)
+export const isDeclaration = (x: any): x is Declaration => ISD(x)
+
+// prettier-ignore
+const IST = is.struct({ kind: is.oneOf('intrinsic', 'literal', 'reference', 'union', 'intersection', 'array', 'tuple', 'function-type', 'type-operator', 'record', 'conditional', 'infer', 'indexed-access', 'mapped', 'query', 'template-literal', 'predicate', 'import-type') }, false)
+export const isType = (x: any): x is Type => IST(x)
+
+// prettier-ignore
+const ISP = is.struct({ kind: is.oneOf('signature', 'parameter', 'generic', 'property', 'method', 'index-signature', 'enum-member', 'tuple-element') }, false)
+export const isPart = (x: any): x is Part => ISP(x)
+
+// prettier-ignore
+const ISK = is.or(ISD, IST, ISP)
+export const isKind = (x: any): x is Any => ISK(x)
+
+// ---------------- Remapped with kind and base ----------------
+export type DeclarationMap = t.MapKind<DeclerationDefinitions, 'kind', Base>
+export type TypeMap = t.MapKind<TypeDefinitions, 'kind', Typebase>
+export type PartMap = t.MapKind<TypeComponentDefinitions, 'kind', Typebase>
+export type KindsMap = DeclarationMap & TypeMap & PartMap
+
+// ---------------- COMMENTS ----------------
+export type CommentPart = t.MapKindUnion<
+  {
+    text: { text: string }
+    link: { target: string; text?: string; style?: 'code' | 'plain' }
+  },
+  'kind'
+>
+
+export interface CommentTagDefinitions {
+  '@param': { name: string; type?: Type; optional?: boolean; default?: string; text: string }
+  '@property': { name: string; type?: NoInfer<Type>; optional?: boolean; default?: string; text: string }
+  '@returns': { type?: Type; text: string }
+  '@throws': { type?: Type; text: string }
+  '@type': { type: Type; text: string }
+  '@satisfies': { type: Type; text: string }
+  '@template': { generics: Part<'generic'>[]; text: string }
+  '@see': { target?: string; text: string }
+  '@example': { caption?: string; code: string; text?: string }
+  '@augments': { class: Type; text: string }
+  '@implements': { class: Type; text: string }
+}
+
+export interface Comment {
+  parts: CommentPart[]
+  /** Block tags. Omitted when empty so the common case stays small. */
+  tags?: CommentTag[]
+}
+
+export type CommentTagMap = t.MapKind<CommentTagDefinitions, 'tag'>
+export type CommentTag<K extends keyof CommentTagMap = keyof CommentTagMap> =
+  | CommentTagMap[K]
+  | { tag: string; name?: string; text: string }
+
+// ---------------- Utilities ----------------

package/src/core/reflect/walk.ts

@@ -0,0 +1,121 @@
+import type * as T from './types.ts'
+
+export interface Visitor {
+  onReference: (ref: T.Type<'reference'>) => void
+  onSources: (sources: T.Source[]) => void
+}
+
+/**
+ * Walk a single declaration's substructure. Modules and namespaces are no-ops
+ * because their children are just ids — every child is reachable through the
+ * flat declaration list separately, so recursing here would double-count.
+ *
+ * Only the per-decl substructure (signatures, types, parameters, …) is walked.
+ */
+export const Declaration = (d: T.Declaration, v: Visitor): void => {
+  switch (d.kind) {
+    case 'module':
+    case 'namespace':
+      return
+    case 'variable':
+      return Variable(d, v)
+    case 'function':
+      return Function(d, v)
+    case 'class':
+      return Class(d, v)
+    case 'interface':
+      return Interface(d, v)
+    case 'type-alias':
+      return TypeAlias(d, v)
+    case 'enum':
+      return Enum(d, v)
+  }
+}
+
+export const Variable = (n: T.Declaration<'variable'>, v: Visitor): void => Type(n.type, v)
+
+export const Function = (n: T.Declaration<'function'>, v: Visitor): void => n.signatures.forEach((s) => Signature(s, v))
+
+export const Class = (n: T.Declaration<'class'>, v: Visitor): void => {
+  n.generics?.forEach((tp) => TypeParameter(tp, v))
+  n.extends?.forEach((t) => Type(t, v))
+  n.implements?.forEach((t) => Type(t, v))
+  n.constructors.forEach((s) => Signature(s, v))
+  n.properties.forEach((p) => Property(p, v))
+  n.methods.forEach((m) => Method(m, v))
+  if (n.indexSignature) IndexSignature(n.indexSignature, v)
+}
+
+export const Interface = (n: T.Declaration<'interface'>, v: Visitor): void => {
+  n.generics?.forEach((tp) => TypeParameter(tp, v))
+  n.extends?.forEach((t) => Type(t, v))
+  n.properties.forEach((p) => Property(p, v))
+  n.methods.forEach((m) => Method(m, v))
+  n.callSignatures?.forEach((s) => Signature(s, v))
+  n.constructSignatures?.forEach((s) => Signature(s, v))
+  if (n.indexSignature) IndexSignature(n.indexSignature, v)
+}
+
+export const TypeAlias = (n: T.Declaration<'type-alias'>, v: Visitor): void => {
+  n.generics?.forEach((tp) => TypeParameter(tp, v))
+  Type(n.type, v)
+}
+
+export const Enum = (n: T.Declaration<'enum'>, _: Visitor): void => {
+  n.members.forEach((_) => {
+    // v.onEnumMember(m)
+  })
+}
+
+export const Property = (n: T.Part<'property'>, v: Visitor): void => Type(n.type, v)
+
+export const Method = (n: T.Part<'method'>, v: Visitor): void => n.signatures.forEach((s) => Signature(s, v))
+
+export const IndexSignature = (n: T.Part<'index-signature'>, v: Visitor): void => {
+  Parameter(n.parameter, v)
+  Type(n.type, v)
+}
+
+export const Signature = (n: T.Part<'signature'>, v: Visitor): void => {
+  n.generics?.forEach((tp) => TypeParameter(tp, v))
+  n.params.forEach((p) => Parameter(p, v))
+  Type(n.return, v)
+}
+
+export const Parameter = (n: T.Part<'parameter'>, v: Visitor): void => Type(n.type, v)
+
+export const TypeParameter = (n: T.Part<'generic'>, v: Visitor): void => {
+  if (n.constraint) Type(n.constraint, v)
+  if (n.default) Type(n.default, v)
+}
+
+export const ObjectLiteral = (n: T.Type<'record'>, v: Visitor): void => {
+  n.properties.forEach((p) => Property(p, v))
+  n.methods.forEach((m) => Method(m, v))
+  n.callSignatures?.forEach((s) => Signature(s, v))
+  n.constructSignatures?.forEach((s) => Signature(s, v))
+  if (n.indexSignature) IndexSignature(n.indexSignature, v)
+}
+
+export const Type = (t: T.Type, v: Visitor): void => {
+  switch (t.kind) {
+    case 'reference':
+      v.onReference(t)
+      t.args?.forEach((a) => Type(a, v))
+      return
+    case 'union':
+    case 'intersection':
+      return t.types.forEach((x) => Type(x, v))
+    case 'array':
+      return Type(t.elementType, v)
+    case 'tuple':
+      return t.elements.forEach((el) => Type(el.type, v))
+    case 'function-type':
+      return t.signatures.forEach((s) => Signature(s, v))
+    case 'type-operator':
+      return Type(t.target, v)
+    case 'record':
+      return ObjectLiteral(t, v)
+    // intrinsic, literal: nothing to do
+  }
+}

package/src/solidjs/index.ts

@@ -0,0 +1 @@
+export * from 'solid-js'

package/src/solidjs/jsx-runtime.ts

@@ -0,0 +1 @@
+export * from 'solid-js/jsx-runtime'

package/src/ui/App.tsx

@@ -0,0 +1,115 @@
+import { Show, createMemo, createEffect, type Accessor } from 'solid-js'
+import { Router, Route, useParams, Navigate } from '@solidjs/router'
+
+import {
+  ThemeProvider,
+  ProjectProvider,
+  type Components,
+  DeclarationScope,
+  useProject,
+  type Types,
+  MarkupProvider,
+} from './context/index.ts'
+import { Link, Page, MarkdownPage, Layout } from './components/index.ts'
+import { setRendered } from './context/global.ts'
+
+/** First navigable route slug — the implicit home target. */
+const firstSlug = (routes: Types.RouteNode[]): string | undefined => (routes.find((r) => r.sidebar) ?? routes[0])?.slug
+
+/** Resolve the current `/*slug` path to a route and render its page. */
+const PathRoute = () => {
+  const params = useParams()
+  const project = useProject()
+  const route = createMemo(() => project().routeForSlug(params['slug'] ?? ''))
+  return (
+    <Show when={route()} fallback={<Fallback slug={params['slug']} />}>
+      {(r) => <RouteView route={r()} />}
+    </Show>
+  )
+}
+
+/** Dispatch a route to the page renderer matching its `page.kind`. */
+const RouteView = (props: { route: Types.RouteNode }) => (
+  <Show
+    when={props.route.page.kind === 'markdown'}
+    fallback={<DeclarationView route={props.route as Types.RouteNode<'declaration' | 'module'>} />}
+  >
+    <MarkdownPage route={props.route as Types.RouteNode<'markdown'>} />
+  </Show>
+)
+
+const DeclarationView = (props: { route: Types.RouteNode<'declaration' | 'module'> }) => {
+  const project = useProject()
+  const decl = createMemo(() => project().byId(props.route.page.id))
+  return (
+    <Show when={decl()} fallback={<NotFound />}>
+      {(d) => (
+        <DeclarationScope id={d().id}>
+          <Page route={props.route} decl={d()} />
+        </DeclarationScope>
+      )}
+    </Show>
+  )
+}
+
+/** Empty path redirects to the first route; anything else is a miss. */
+const Fallback = (props: { slug?: string }) => {
+  const project = useProject()
+  const first = createMemo(() => firstSlug(project()?.routes ?? []))
+  return (
+    <Show when={!props.slug && first} fallback={<NotFound />}>
+      {(slug) => <Navigate href={`/${slug()}`} />}
+    </Show>
+  )
+}
+
+/** Fallback for routes that don't match a registered path. */
+const NotFound = () => (
+  <div class="py-20 text-center">
+    <h1 class="text-2xl font-semibold mb-2">Not found</h1>
+    <p class="text-mute">No page matches this URL.</p>
+    <Link href="/">Back home</Link>
+  </div>
+)
+
+/**
+ * Stock route table. Exported on its own so a custom `App` can drop it in
+ * under a different root, add prefixes, or compose alongside extra routes.
+ */
+export const Routes = () => <Route path="/*slug" component={PathRoute} />
+
+/**
+ * One-shot app shell: theme context, router, default Layout. Replace any
+ * one of the pieces — `ThemeProvider`, `Layout`, `Routes` — and you keep
+ * the others.
+ */
+export const App = (props: {
+  json: Accessor<Types.ProjectJson | null> | Types.ProjectJson | null
+  components?: Accessor<Components> | Components
+}) => {
+  createEffect(() => {
+    setRendered(true)
+    return () => setRendered(false)
+  })
+  return (
+    <Show
+      when={createMemo(() => (typeof props.json === 'function' ? props.json() : props.json))()}
+      fallback={<div>No docs...</div>}
+    >
+      {(json) => (
+        <ProjectProvider
+          json={json}
+          components={typeof props.components === 'function' ? props.components() : props.components}
+        >
+          <ThemeProvider>
+            <MarkupProvider>
+              <Router root={(p) => <Layout>{p.children}</Layout>}>
+                <Routes />
+              </Router>
+            </MarkupProvider>
+          </ThemeProvider>
+        </ProjectProvider>
+      )}
+    </Show>
+  )
+}

package/src/ui/components/Breadcrumb.tsx

@@ -0,0 +1,53 @@
+import { For, Show, createMemo } from 'solid-js'
+import { A } from '@solidjs/router'
+
+import { createSlot, useProject, type Types } from '../context/index.ts'
+
+type Crumb = { label: string; href?: string }
+
+export const Breadcrumb = createSlot('page.header.breadcrumb', (props: { id: number }) => {
+  const project = useProject()
+  const crumbs = createMemo(() => buildCrumbs(project(), props.id))
+
+  return (
+    <nav class="text-xs text-mute mb-3" aria-label="Breadcrumb">
+      <ol class="flex items-center gap-1.5 flex-wrap">
+        <li>
+          <A href="/" class="hover:text-fg">
+            {project().name}
+          </A>
+        </li>
+        <For each={crumbs()}>
+          {(c, i) => (
+            <>
+              <li class="text-mute opacity-60">/</li>
+              <li>
+                <Show when={c.href && i() < crumbs().length - 1} fallback={<span class="text-fg">{c.label}</span>}>
+                  <A href={c.href!} class="hover:text-fg">
+                    {c.label}
+                  </A>
+                </Show>
+              </li>
+            </>
+          )}
+        </For>
+      </ol>
+    </nav>
+  )
+})
+
+/**
+ * One crumb per slug segment, so every module level is reachable — each prefix
+ * resolves through `routeForSlug`, which returns pages even when they aren't in
+ * the sidebar. Levels with no page render as plain text.
+ */
+const buildCrumbs = (project: Types.Project, id: number): Crumb[] => {
+  const route = project.routeForId(id)
+  if (!route?.slug) return []
+  const segs = route.slug.split('/')
+  return segs.map((seg, i) => {
+    const prefix = segs.slice(0, i + 1).join('/')
+    const r = project.routeForSlug(prefix)
+    return { label: r?.label ?? seg, href: r ? `/${prefix}` : undefined }
+  })
+}

package/src/ui/components/Code/index.tsx

@@ -0,0 +1,112 @@
+import { createEffect, createMemo, createSignal, onCleanup, Show } from 'solid-js'
+import { CodeJar } from 'codejar'
+import { cn } from '@lickle/cn'
+
+import { useMarkup, useCodeToHtml, type Highlighter } from '../../context/index.ts'
+
+export const Code = (props: { code: string; lang?: string }) => {
+  const html = useCodeToHtml({ ...props, structure: 'inline' })
+  const visibility = createMemo(() => (html() ? 'opacity-100' : 'opacity-0'))
+  const className = createMemo(() => cn('transition-opacity duration-200', visibility()))
+  return (
+    <code class={className()}>
+      <Show when={html()} fallback={<pre class="h-12 w-full" />}>
+        {(h) => <pre innerHTML={h()} />}
+      </Show>
+    </code>
+  )
+}
+
+export const CodeBlock = (props: { code: string; lang?: string }) => (
+  <div class="bg-code-bg border border-line rounded-lg p-4">
+    <Code code={props.code} lang={props.lang} />
+  </div>
+)
+
+type CodeEditorProps = {
+  lang?: string
+  readonly?: boolean
+  value: () => string
+  onChange?: (code: string) => void
+}
+
+export const CodeEditor = (props: CodeEditorProps) => {
+  const editor = useCodeEditor(props)
+  return <div ref={editor.onBind} spellcheck={false} />
+}
+
+const useCodeEditor = (props: CodeEditorProps) => {
+  const markup = useMarkup()
+  let _jar: ReturnType<typeof CodeJar> | null = null
+  let _host: HTMLElement | null = null
+  let initialized = false
+  let current = props.value()
+
+  const [jar, setJar] = createSignal<ReturnType<typeof CodeJar> | null>(null)
+
+  const setup = (host: HTMLElement, h: Highlighter) => {
+    if (initialized) return
+    initialized = true
+    _jar = CodeJar(
+      host,
+      (el) => {
+        try {
+          el.innerHTML = h.codeToHtml({ text: el.textContent ?? '', lang: props.lang })
+        } catch (err) {
+          console.warn('[Editor] highlight failed', err)
+        }
+      },
+      {
+        preserveIdent: true,
+        addClosing: true,
+      },
+    )
+
+    _jar.updateCode(current)
+    _jar.onUpdate(() => {
+      current = host.innerText
+      props.onChange?.(host.innerText)
+    })
+    if (props.readonly) host.contentEditable = 'false'
+    setJar(_jar)
+  }
+
+  const teardown = () => {
+    _jar?.destroy()
+    initialized = false
+  }
+
+  const init = () => {
+    const h = markup.highlighter()
+    const el = _host
+    if (h && el) setup(el, h)
+  }
+
+  createEffect(init)
+
+  createEffect(() => {
+    const v = props.value()
+    const j = jar()
+    if (j && current !== v) {
+      j.updateCode(v)
+      current = v
+    }
+  })
+
+  onCleanup(() => {
+    jar()?.destroy()
+    initialized = false
+  })
+
+  const onBind = (h: HTMLElement | null) => {
+    if (_host === h) return
+    if (!h) {
+      teardown()
+      _host = null
+      return
+    }
+    _host = h
+    init()
+  }
+  return { onBind, jar }
+}