@lickle/docs 0.0.0-dev.1

package/src/core/project/routing.ts

@@ -0,0 +1,234 @@
+import type { RouteNode, PageType } from './types.ts'
+import * as reflect from '../reflect/index.ts'
+import * as config from '../../config/load.ts'
+import * as naming from './naming.ts'
+
+type Page = 'declaration' | 'module'
+
+export type Options = {
+  rootName: string
+  entrypoints?: config.Entry[]
+  /** Override how routes are named / grouped / shown. Defaults to {@link createRouteProvider}. */
+  provider?: RouteProvider
+  /**
+   * `'exposed'` (default) routes only the public API reachable through exports.
+   * `'full'` routes every scanned declaration, grouped under its own module —
+   * including internal, non-exported ones.
+   */
+  mode?: 'exposed' | 'full'
+  /** Slugs already taken by routes built elsewhere (e.g. a README home page). */
+  reserved?: Iterable<string>
+}
+
+// ----------------------------------------------------------------------------
+// Provider abstraction
+// ----------------------------------------------------------------------------
+
+/** Everything a provider needs to decide a single route, computed top-down. */
+export type RouteContext = {
+  /** The declaration this route points at. */
+  decl: reflect.Declaration
+  /** Exposure alias on this path (set by renames / `export * as`). */
+  alias?: string
+  /** Resolved parts of the parent route; `undefined` at an entry module. */
+  parent?: naming.Parts
+  /** The reflect index, for providers that need to inspect the graph. */
+  index: reflect.Index
+  /** Naming options (project name, entry aliases, common dir). */
+  options: naming.NameOptions
+}
+
+/**
+ * Customisation seam for the route tree. The traversal, de-duplication and
+ * page wiring stay in {@link buildRoutes}; a provider only decides per-route
+ * presentation. Build one with {@link createRouteProvider} and override the
+ * parts you care about.
+ */
+export interface RouteProvider {
+  /** Label, slug and qualified name for the route. */
+  name(cx: RouteContext): naming.Parts
+  /** Whether the route appears in navigation (the sidebar). */
+  nav(cx: RouteContext): boolean
+  /** Optional group heading rendered above the route in navigation. */
+  group(cx: RouteContext): string | undefined
+}
+
+/** Default naming: entry modules from their path/alias, everything else nested under its parent. */
+const defaultName = (cx: RouteContext): naming.Parts =>
+  cx.parent === undefined
+    ? naming.rootParts(cx.decl as reflect.Declaration<'module'>, cx.options)
+    : naming.childParts(cx.alias ?? cx.decl.name, cx.parent)
+
+/**
+ * Compose a provider from optional overrides; unset hooks fall back to the
+ * stock behaviour (path-derived names, everything navigable, no groups).
+ */
+export const createRouteProvider = (overrides: Partial<RouteProvider> = {}): RouteProvider => ({
+  name: overrides.name ?? defaultName,
+  nav: overrides.nav ?? (() => true),
+  group: overrides.group ?? (() => undefined),
+})
+
+// ----------------------------------------------------------------------------
+// Build
+// ----------------------------------------------------------------------------
+
+/**
+ * Build the navigation tree from the reflect index. The shape mirrors the
+ * exposure graph (`index.exposed`) rather than the raw declaration tree, so
+ * `export * from`, `export * as ns`, renames and namespaces are already
+ * resolved. Each declaration is routed once — the first exposure path wins —
+ * which keeps slugs unique and avoids duplicate pages.
+ */
+export const buildRoutes = (index: reflect.Index, opts: Options): RouteNode<Page>[] => {
+  const options: naming.NameOptions = {
+    rootName: opts.rootName,
+    aliases: new Map((opts.entrypoints ?? []).map((e) => [e.path, e.as.replace(/^\.\//, '')])),
+    commonDir: index.commonDir(),
+  }
+  const provider = opts.provider ?? createRouteProvider()
+  const full = opts.mode === 'full'
+  const seen = new Set<number>()
+
+  // Keep slugs unique across the whole tree (and any reserved/README slugs).
+  // The empty root slug falls back to `index` so a README can own `/`.
+  const usedSlugs = new Set<string>(opts.reserved ?? [])
+  const uniqueSlug = (slug: string): string => {
+    if (!usedSlugs.has(slug)) return (usedSlugs.add(slug), slug)
+    const base = slug || 'index'
+    let next = base
+    for (let n = 2; usedSlugs.has(next); n++) next = `${base}-${n}`
+    return (usedSlugs.add(next), next)
+  }
+
+  // Children of a route: the exposure graph in `exposed` mode, the raw
+  // declaration tree (minus re-export clauses) in `full` mode.
+  const childrenOf = (id: number): Iterable<{ id: number; alias?: string }> => {
+    if (!full) return index.exposed(id)
+    const out: { id: number }[] = []
+    for (const c of index.children(id)) if (c.kind !== 'export') out.push({ id: c.id })
+    return out
+  }
+
+  // Canonical parts for every routed declaration, so a page re-exposed
+  // elsewhere can link back to where it actually lives. Seeded with the roots
+  // up front (below) so a root re-exported by another resolves to its own slug.
+  const routed = new Map<number, naming.Parts>()
+
+  const nameOf = (id: number, parent?: naming.Parts, alias?: string): naming.Parts => {
+    const named = provider.name({ decl: index.get(id)!, alias, parent, index, options })
+    return { ...named, slug: uniqueSlug(named.slug) }
+  }
+
+  const makePage = (id: number, parts: naming.Parts): PageType<Page> => ({
+    kind: index.get(id)!.kind === 'module' ? 'module' : 'declaration',
+    id,
+    alias: parts.label,
+    qualified: parts.qualified,
+    referencedIn: [...index.referencedIn(id)],
+  })
+
+  // A page already owned by another route, surfaced here as a link only: it
+  // shows in the parent's child list but stays out of the sidebar and carries
+  // no subtree, so clicking it lands on the canonical route.
+  const linkNode = (
+    id: number,
+    parent: naming.Parts,
+    alias: string | undefined,
+    canon: naming.Parts,
+  ): RouteNode<Page> => {
+    const cx: RouteContext = { decl: index.get(id)!, alias, parent, index, options }
+    const group = provider.group(cx)
+    return {
+      label: provider.name(cx).label,
+      slug: canon.slug,
+      page: makePage(id, canon),
+      children: [],
+      sidebar: false,
+      ...(group ? { group } : {}),
+    }
+  }
+
+  const buildRoute = (id: number, parent?: naming.Parts, alias?: string): RouteNode<Page> => {
+    const decl = index.get(id)!
+    const cx: RouteContext = { decl, alias, parent, index, options }
+    const parts = routed.get(id) ?? nameOf(id, parent, alias)
+    routed.set(id, parts)
+
+    seen.add(id)
+    const children: RouteNode<Page>[] = []
+    for (const e of childrenOf(id)) {
+      if (e.id === id) continue
+      if (seen.has(e.id)) {
+        const canon = routed.get(e.id)
+        if (canon) children.push(linkNode(e.id, parts, e.alias, canon))
+        continue
+      }
+      children.push(buildRoute(e.id, parts, e.alias))
+    }
+
+    const group = provider.group(cx)
+    return {
+      label: parts.label,
+      slug: parts.slug,
+      page: makePage(id, parts),
+      children,
+      sidebar: provider.nav(cx),
+      ...(group ? { group } : {}),
+    }
+  }
+
+  // `full` lists every module; `exposed` only the entrypoints. Name (and slug-
+  // reserve) every root up front so one re-exported by another stays top-level
+  // and re-exposures resolve to its canonical slug.
+  const roots = full ? [...index.declarations()].filter((d) => d.kind === 'module') : [...index.roots()]
+  for (const r of roots) (seen.add(r.id), routed.set(r.id, nameOf(r.id)))
+
+  // Build a root *after* any entrypoint modules it re-exports, so a declaration
+  // reachable both directly (a barrel `export *`) and through its own module is
+  // owned by the module — the barrel only links to it. Display order is kept as
+  // the config order regardless.
+  const built = new Map<number, RouteNode<Page>>()
+  for (const id of buildOrder(roots, index)) built.set(id, buildRoute(id))
+  return roots.map((root) => built.get(root.id)!)
+}
+
+/**
+ * Roots topologically sorted so an entrypoint module is built before any other
+ * root that re-exports its declarations (a barrel `export *`). That way each
+ * declaration is owned by the module that defines it, and the barrel only links.
+ */
+const buildOrder = (roots: reflect.Declaration[], index: reflect.Index): number[] => {
+  const rootIds = new Set(roots.map((r) => r.id))
+
+  // The entrypoint module a declaration is defined in (walk to its module ancestor).
+  const moduleOf = (id: number): number | undefined => {
+    let d = index.get(id)
+    while (d && d.kind !== 'module') d = index.get(d.parent)
+    return d?.id
+  }
+
+  // Roots whose declarations `rootId` re-exposes from elsewhere.
+  const deps = (rootId: number): Iterable<number> => {
+    const out = new Set<number>()
+    for (const e of index.exposed(rootId)) {
+      const m = moduleOf(e.id)
+      if (m !== undefined && m !== rootId && rootIds.has(m)) out.add(m)
+    }
+    return out
+  }
+
+  const order: number[] = []
+  const placed = new Set<number>()
+  const stack = new Set<number>()
+  const visit = (id: number): void => {
+    if (placed.has(id) || stack.has(id)) return
+    stack.add(id)
+    for (const dep of deps(id)) visit(dep)
+    stack.delete(id)
+    placed.add(id)
+    order.push(id)
+  }
+  for (const r of roots) visit(r.id)
+  return order
+}

package/src/core/project/types.ts

@@ -0,0 +1,47 @@
+import { type t } from '../../_lib/index.ts'
+
+import * as reflect from '../reflect/index.ts'
+import * as config from '../../config/load.ts'
+
+/** Description of the project persisted to json used to generate the site */
+export interface ProjectJson {
+  /** The name of the project. */
+  name: string
+  /** The version of the project. */
+  version?: string
+  /** Repository information */
+  repository?: config.Repo
+  /** Links for the project. */
+  links: config.Link[]
+  /** Entrypoints — relative source paths reachable from `main` / `exports`. */
+  entrypoints: config.Entry[]
+  /** Routes of the project. */
+  routes: RouteNode[]
+  /** Flat list of every declaration in the project, source order. */
+  declarations: reflect.Declaration[]
+}
+
+/** Used to generate navigation, for now all declarations are pages */
+export type BaseRoute<P> = {
+  /** Label used in the navigation */
+  label: string
+  /** Slug of the page, used in the URL */
+  slug: string
+  /** Page type to display */
+  page: P
+  /** sub pages */
+  children: BaseRoute<P>[]
+  /** Whether the page should be displayed in the navigation */
+  sidebar: boolean
+  /** Adds a label above in navigation*/
+  group?: string
+}
+
+type PageTypeMap = t.MapKind<{
+  markdown: { content: string }
+  module: { id: number; alias?: string; qualified: string; referencedIn: number[] }
+  declaration: { id: number; alias?: string; qualified: string; referencedIn: number[] }
+}>
+
+export type PageType<K extends keyof PageTypeMap = keyof PageTypeMap> = PageTypeMap[K]
+export type RouteNode<K extends keyof PageTypeMap = keyof PageTypeMap> = BaseRoute<PageType<K>>

package/src/core/reflect/index.ts

@@ -0,0 +1,18 @@
+import type { ScanOptions } from './state.ts'
+
+import * as indexed from './indexed.ts'
+import { resolve } from './resolve.ts'
+import { scan } from './scan.ts'
+
+export type { ScanOptions } from './state.ts'
+export { type Index } from './indexed.ts'
+export type * from './types.ts'
+
+export const generate = (rootFiles: { as: string; path: string }[], options: ScanOptions) => {
+  const s = scan(
+    rootFiles.map((r) => r.path),
+    options,
+  )
+  const r = resolve(s)
+  return indexed.create(r, rootFiles)
+}

package/src/core/reflect/indexed.ts

@@ -0,0 +1,242 @@
+import { path, type t } from '../../_lib/index.ts'
+import type { ScanState } from './state.ts'
+import * as T from './types.ts'
+
+export const create = (s: ScanState, entries: { as: string; path: string }[]) =>
+  index(s, [roots(entries), treeIndex, referenceIndex, exposerIndex])
+
+export type Index = Roots & TreeIndex & ReferenceIndex & ExposerIndex
+
+/** */
+export type Roots = {
+  roots(): Iterable<T.Declaration<'module'>>
+  commonDir: () => string
+  modules: () => T.Declaration<'module'>[]
+}
+export const roots =
+  (entries: { as: string; path: string }[]): Indexer<Roots> =>
+  (b): Roots => {
+    const roots = new Map<string, T.Declaration<'module'>>()
+    const modules: T.Declaration<'module'>[] = []
+    const byPath = new Map<string, number>()
+    let commonDir = ''
+    b.init((d) => {
+      if (d.kind === 'module' && d.path) {
+        modules.push(d)
+        byPath.set(d.path, d.id)
+        for (const entry of entries) {
+          if (d.path === entry.path) {
+            roots.set(entry.as, d)
+            break
+          }
+        }
+      }
+    })
+    b.after(() => {
+      commonDir = path.common(Array.from(byPath.keys()))
+    })
+    return { roots: () => roots.values(), commonDir: () => commonDir, modules: () => modules }
+  }
+
+export type TreeIndex = {
+  get: (id: number) => T.Declaration | undefined
+  children: (id: number) => Iterable<T.Declaration>
+  declarations: () => Iterable<T.Declaration>
+}
+export const treeIndex: Indexer<TreeIndex> = (s): TreeIndex => {
+  const byId = new Map<number, T.Declaration>()
+  const byParent = new Map<number, Set<number>>()
+  s.init((d) => {
+    byId.set(d.id, d)
+    const parent = d.parent
+    let children = byParent.get(parent)
+    if (!children) byParent.set(parent, (children = new Set()))
+    children.add(d.id)
+  })
+  const EMPTY = new Set<number>()
+  return {
+    get: (id) => byId.get(id),
+    *children(id) {
+      for (const child of byParent.get(id) ?? EMPTY) yield byId.get(child)!
+    },
+    declarations: () => byId.values(),
+  }
+}
+
+/** */
+export type ReferenceIndex = { referencedIn: (id: number) => Iterable<number> }
+export const referenceIndex: Indexer<ReferenceIndex> = (s): ReferenceIndex => {
+  const referencedIn = new Map<number, Set<number>>()
+  for (const ref of s.references) {
+    if (ref.type === 'internal') {
+      let refs = referencedIn.get(ref.targetId)
+      if (!refs) referencedIn.set(ref.targetId, (refs = new Set()))
+      refs.add(ref.owner)
+    }
+  }
+  const EMPTY = new Set<number>()
+  return { referencedIn: (id) => referencedIn.get(id) ?? EMPTY }
+}
+
+/** Depends on Roots + TreeIndex. */
+export type Exposure = { exposer: number; alias?: string }
+export type Exposed = { id: number; alias?: string }
+export type ExposedModule =
+  | { id: number; kind: 'star' }
+  | { id: number; kind: 'namespace'; alias: string }
+  | { id: number; kind: 'named'; names: {}[] }
+
+export type ExposerIndex = {
+  exposedBy: (id: number) => Iterable<Exposure>
+  exposes: (id: number) => Iterable<Exposed>
+  /** Declarations exposed directly (one level) by `exposer`, in exposure order. */
+  exposed: (exposer: number) => Iterable<Exposed>
+  /**
+   * Exposed modules / namespaces. With no argument, every one (deduped by id);
+   * with an exposer id, only those exposed directly by that module/namespace.
+   */
+  exposedModules: (exposer?: number) => Iterable<ExposedModule>
+}
+export const exposerIndex: Indexer<ExposerIndex, Roots & TreeIndex> = (b, deps) => {
+  const exposedBy = new Map<number, Exposure[]>()
+  const direct = new Map<number, Exposed[]>()
+  const exposedModules = new Map<number, ExposedModule>()
+  const modulesByExposer = new Map<number, Map<number, ExposedModule>>()
+
+  const setModule = (exposer: number, m: ExposedModule): void => {
+    exposedModules.set(m.id, m)
+    let g = modulesByExposer.get(exposer)
+    if (!g) modulesByExposer.set(exposer, (g = new Map()))
+    g.set(m.id, m)
+  }
+
+  // Records id under exposer/alias. Returns whether this (exposer → id) edge
+  // is new — used to stop infinite recursion on cycles, NOT to globally
+  // dedup, since the same id can be exposed by many exposers.
+  const seenEdge = new Set<string>()
+  const record = (id: number, exposer: number, alias?: string): boolean => {
+    const edge = exposer + ':' + id
+    if (seenEdge.has(edge)) return false
+    seenEdge.add(edge)
+
+    let by = exposedBy.get(id)
+    if (!by) exposedBy.set(id, (by = []))
+    by.push({ exposer, alias })
+
+    let list = direct.get(exposer)
+    if (!list) direct.set(exposer, (list = []))
+    list.push({ id, alias })
+    return true
+  }
+
+  // Public members of a module / namespace: exported declarations plus the
+  // `export …` statements themselves (which carry re-exports). Internal,
+  // non-exported helpers are left out of the exposure graph.
+  const members = function* (id: number): Iterable<T.Declaration> {
+    for (const child of deps.children(id)) if (child.exported) yield child
+  }
+
+  const expose = (id: number, exposer: number, alias?: string): void => {
+    const d = deps.get(id)
+    if (!d) return
+    if (d.kind === 'export') {
+      for (const name of d.names) {
+        if (d.star && name.name) {
+          const target = deps.get(name.ref)
+          if (target?.kind === 'module' || target?.kind === 'namespace') {
+            setModule(exposer, { id: name.ref, kind: 'namespace', alias: name.name })
+          }
+          if (record(name.ref, exposer, name.name)) {
+            for (const child of members(name.ref)) expose(child.id, name.ref)
+          }
+        } else if (d.star) {
+          if (deps.get(name.ref)?.kind === 'module') setModule(exposer, { id: name.ref, kind: 'star' })
+          for (const child of members(name.ref)) expose(child.id, exposer)
+        } else {
+          if (deps.get(name.ref)?.kind === 'module') addNamed(exposer, name.ref, name.name)
+          expose(name.ref, exposer, name.name)
+        }
+      }
+      return
+    }
+    if (d.kind === 'namespace') {
+      setModule(exposer, { id, kind: 'namespace', alias: alias ?? d.name })
+      if (record(id, exposer, alias ?? d.name)) {
+        for (const child of members(id)) expose(child.id, id)
+      }
+      return
+    }
+    // A re-exported module (`export * as ns from './m'`) nests its members.
+    if (d.kind === 'module') {
+      if (record(id, exposer, alias ?? d.name)) {
+        for (const child of members(id)) expose(child.id, id)
+      }
+      return
+    }
+    record(id, exposer, alias ?? d.name)
+  }
+
+  // A module pulled in by a plain `export { … }` accumulates its named members.
+  const addNamed = (exposer: number, id: number, name: string): void => {
+    const m = exposedModules.get(id)
+    if (m?.kind === 'named') {
+      m.names.push({ name })
+      setModule(exposer, m)
+    } else {
+      setModule(exposer, { id, kind: 'named', names: [{ name }] })
+    }
+  }
+
+  b.after(() => {
+    for (const root of deps.roots()) {
+      for (const child of members(root.id)) expose(child.id, root.id)
+    }
+  })
+
+  const EMPTY_BY: Exposure[] = []
+  const EMPTY_EXP: Exposed[] = []
+  const exposes = function* (id: number): Iterable<Exposed> {
+    for (const e of direct.get(id) ?? EMPTY_EXP) {
+      yield e
+      yield* exposes(e.id)
+    }
+  }
+  const EMPTY_MODULES = new Map<number, ExposedModule>()
+  return {
+    exposedBy: (id) => exposedBy.get(id) ?? EMPTY_BY,
+    exposes: (id) => exposes(id),
+    exposed: (id) => direct.get(id) ?? EMPTY_EXP,
+    exposedModules: (exposer) =>
+      exposer === undefined ? exposedModules.values() : (modulesByExposer.get(exposer) ?? EMPTY_MODULES).values(),
+  }
+}
+
+// -------------------------------------------
+// -- Little abstraction ----------------
+// -------------------------------------------
+interface IndexBuilder {
+  references: T.Type<'reference'>[]
+
+  init: (cb: (d: T.Declaration) => void) => void
+  after: (cb: () => void) => void
+}
+
+// An indexer declares its dependencies (Deps) and produces an output (Out).
+type Indexer<Out extends {} = {}, Deps extends {} = {}> = (b: IndexBuilder, deps: Deps) => Out
+
+export const index = <const T extends Indexer<any, any>[]>(
+  s: ScanState,
+  indexers: T,
+): t.Compute<t.UnionToIntersection<ReturnType<T[number]>>> => {
+  const inits: ((d: T.Declaration) => void)[] = []
+  const afters: (() => void)[] = []
+  const builder: IndexBuilder = { ...s, init: (cb) => inits.push(cb), after: (cb) => afters.push(cb) }
+
+  // `acc` accumulates results and is passed as `deps` to each subsequent indexer.
+  const acc = {} as any
+  for (const indexer of indexers) Object.assign(acc, indexer(builder, acc))
+  for (const d of s.declarations) for (const init of inits) init(d)
+  for (const after of afters) after()
+
+  return acc
+}