antora-modules.d.ts

/*

    # TODO:

    - [ ] Not sure about "@antora/types" because there's no physical module for that. Maybe there should be a 
        types-only package within the antora lerna tree?
    - [ ] Get Dan to vet names for types, and fill in any props I've missed - particularly AntoraFile
    - [ ] Get Dan to confirm what's optional vs nullable vs required
    - [ ] Do we want to use namespaces for things like the objects within a Playbook? 
        Or just code the structures in? 
        Or just declare at module level?
    - [ ] Make sure each module decl only imports types it actually needs
    - [ ] Remove all the unknowns, ofc

*/

declare module "@antora/types" {
    import VinylFile from "vinyl";

    interface AntoraFile {
        asciidoc?: AntoraFile.AsciidocMetadata;
        mediaType?: string | false;
        nav?: { index: number };
        out?: AntoraFile.Destination;
        pub?: AntoraFile.Destination;
        rel?: AntoraFile;
        src?: AntoraFile.Source;
        type?: FileType;
    }

    interface AntoraVinylFile extends AntoraFile, VinylFile {
        _isVinyl: true;
    }

    namespace AntoraFile {
        interface AsciidocMetadata {
            doctitle?: string;
            attributes: AsciidocAttribs;
        }

        interface Destination {
            path?: string;
            basename?: string;
            dirname?: string;
            moduleRootPath?: string;
            rootPath?: string;
            canonicalUrl?: string;
            url?: string;
        }

        interface Source {
            abspath?: string;
            basename: string;
            component: string;
            editUrl?: string;
            extname?: string;
            family: FileFamily;
            mediaType: string | false;
            module: string;
            moduleRootPath?: string;
            origin?: GitOrigin;
            path?: string;
            relative: string;
            stem: string;
            version: string;
        }
    }

    interface GitOrigin {
        branch: string;
        editUrlPattern: string;
        startPath: string;
        type: string;
        url: string;
        worktree?: boolean;
    }

    type FileFamily = "alias" | "attachment" | "example" | "image" | "nav" | "page" | "partial";

    type FileType = "static" | "layout" | "helper" | "partial" | "asset";

    export interface Env {
        [k: string]: string;
    }

    export interface Playbook {
        asciidoc: Playbook.AsciidocConfig;
        content: Playbook.ContentConfig;
        dir: string;
        file: string;
        git: Playbook.GitConfig;
        output: Playbook.OutputConfig;
        runtime: Playbook.RuntimeConfig;
        site: Playbook.SiteConfig;
        ui: Playbook.UIConfig;
        urls: Playbook.URLsConfig;
    }

    namespace Playbook {
        interface AsciidocConfig {
            attributes: AsciidocAttribs;
            extensions: Array<string>;
        }

        interface ContentConfig {
            branches: Array<string>;
            tags: Array<string>;
            sources: Array<ContentSource>;
        }

        interface ContentSource {
            url: string;
            branches: string;
            startPath?: string;
        }

        interface GitConfig {
            credentials: {
                path: string | undefined;
                contents: string | undefined;
            };
        }

        interface OutputConfig {
            clean: boolean;
            dir: string;
            destinations: Array<string> | undefined;
        }

        interface RuntimeConfig {
            cacheDir: string | undefined;
            fetch: boolean;
            pull: boolean | undefined;
            quiet: boolean;
            silent: boolean;
        }

        interface SiteConfig {
            startPage: string | undefined;
            title: string | undefined;
            url: string | undefined;
            keys: { [k: string]: string | undefined };
        }

        interface UIConfig {
            bundle: {
                url: string | null;
                snapshot: boolean;
                startPath: string;
            };
            defaultLayout: string | undefined;
            outputDir: string;
            supplementalFiles: string | Array<AntoraFile> | undefined;
        }

        interface URLsConfig {
            htmlExtensionStyle: HtmlExtensionStyle;
            redirectFacility: "disabled" | "netlify" | "nginx" | "static";
        }
    }

    type HtmlExtensionStyle = "default" | "drop" | "indexify";

    interface AsciidocAttribs {
        [k: string]: any;
    }

    export interface ComponentContent {
        name: string;
        title: string;
        version: string;
        start_page: string;
        nav: Array<string>;
        files: Array<AntoraFile>;
    }

    export interface ContentCatalog {
        htmlUrlExtensionStyle: HtmlExtensionStyle;

        registerComponentVersion(name: string, version: string, options?: ContentCatalog.ComponentOptions): void;
        addFile(file: AntoraFile): void;
        findBy(criteria: ContentCatalog.FileSourceCriteria): Array<AntoraFile>;
        getById(id: ContentCatalog.CompositeDocId): AntoraFile | undefined;
        getByPath(details: ContentCatalog.PathDetails): AntoraFile | undefined;
        getComponent(name: string): ContentCatalog.Component | undefined;
        getComponentVersion(component: string | ContentCatalog.Component, version: string): ContentCatalog.Component | undefined;
        getComponentMap(): ContentCatalog.ComponentMap;
        getComponentMapSortedBy(prop: string): ContentCatalog.ComponentMap;
        getComponents(): Array<ContentCatalog.Component>;
        getComponentsSortedBy(prop: string): Array<ContentCatalog.Component>;
        getFiles(): Array<AntoraFile>;
        getSiteStartPage(): string | undefined;
        registerPageAlias(aliasSpec: string, targetPage: AntoraFile): void;
        resolvePage(spec: string, context: ContentCatalog.Context): AntoraFile | undefined;
        resolveResource(
            spec: string,
            context: ContentCatalog.Context,
            permittedFamilies?: Array<FileFamily>,
            defaultFamily?: FileFamily
        ): AntoraFile | undefined;
    }

    namespace ContentCatalog {
        interface ComponentOptions {
            displayVersion?: string;
            prerelease?: string;
            title?: string;
            startPage?: string;
        }

        type FileSourceCriteria = Partial<AntoraFile>;

        interface CompositeDocId {
            component: string;
            version: string;
            module: string;
            family: FileFamily;
            relative: string;
        }

        interface PathDetails {
            component: string;
            version: string;
            path: string;
        }

        interface Component {
            name: string;
            latest: ComponentVersion;
            versions: Array<ComponentVersion>;
        }

        interface ComponentVersion {
            version: string;
            displayVersion: string;
            title: string;
            url: string;
        }

        interface PageVersion extends ComponentVersion {
            latest?: boolean;
            missing?: boolean;
        }

        interface ComponentMap {
            [k: string]: Component;
        }

        interface Context {
            component: string;
            version: string;
            module: string;
        }
    }

    interface UiCatalog {
        getFiles(): Array<AntoraFile>;
        addFile(file: AntoraFile): void;
        findByType(type: string): Array<AntoraFile>;
    }

    namespace AsciiDoctor {
        interface Config {
            attributes: AsciidocAttribs;
        }

        type Document = unknown; // TODO: figure out something for this
    }

    export interface NavigationCatalog {
        addTree(component: string, version: string, tree: NavigationCatalog.NavItem): Array<NavigationCatalog.NavItem>;
        getNavigation(component: string, version: string): Array<NavigationCatalog.NavItem>;
    }

    namespace NavigationCatalog {
        interface NavItem {
            content?: string;
            items?: Array<NavItem>;
            order?: number;
            root?: boolean;
            url?: string;
            hash?: string;
            urlType?: URLType;
        }

        type URLType = "internal" | "external" | "fragment";
    }

    function composePage(file: AntoraFile, contentCatalog: ContentCatalog, navigationCatalog: NavigationCatalog): AntoraFile;
    type PageComposer = typeof composePage;

    namespace PageComposer {
        interface SiteUiModel {
            title: string;
            path: string;
            url: string;
            components: ContentCatalog.ComponentMap;
            keys: { [k: string]: string };
            ui: {
                url: string;
                defaultLayout: string;
            };
        }

        interface PageUiModel extends NavContext {
            contents: Buffer | NodeJS.ReadableStream | null;
            layout: string;
            title: string;
            url: string;
            description: string;
            keywords: string;
            attributes: AsciidocAttribs;
            component: ContentCatalog.Component;
            version: string;
            displayVersion: string;
            componentVersion: ContentCatalog.ComponentVersion;
            module: string;
            origin?: GitOrigin;
            versions: Array<ContentCatalog.PageVersion>;
            navigation: Array<NavigationCatalog.NavItem>;
            editUrl: string;
            home: boolean;
            latest: ContentCatalog.PageVersion;
            canonicalUrl?: string;
        }

        interface UiModel {
            antoraVersion: string;
            env: Env;
            page: PageUiModel;
            site: SiteUiModel;
            siteRootPath: string;
            uiRootPath: string;
        }

        interface NavContext {
            breadcrumbs: Array<PageNavItem>;
            parent?: PageNavItem;
            previous?: PageNavItem;
            next?: PageNavItem;
        }

        interface PageNavItem extends NavigationCatalog.NavItem {
            current?: PageNavItem;
            ancestors?: PageNavItem;
            previous?: PageNavItem;
            next?: PageNavItem;
            seekNext?: boolean;
            discrete?: boolean;
        }
    }

    interface Catalog {
        getFiles(): Array<AntoraFile>;
    }
}

declare module "@antora/playbook-builder" {
    import { Env, Playbook, NavigationCatalog } from "@antora/types";

    function buildPlaybook(args: Array<string>, env: Env): Promise<Playbook>;

    export = buildPlaybook;
}

declare module "@antora/content-aggregator" {
    import { Playbook, ComponentContent } from "@antora/types";

    function aggregateContent(playbook: Playbook): Promise<Array<ComponentContent>>;

    export = aggregateContent;
}

declare module "@antora/content-classifier" {
    import { Playbook, ComponentContent, ContentCatalog } from "@antora/types";

    function classifyContent(playbook: Playbook, contentAggregate: Array<ComponentContent>): ContentCatalog;

    export = classifyContent;
}

declare module "@antora/ui-loader" {
    import { Playbook, UiCatalog } from "@antora/types";

    function loadUi(playbook: Playbook): Promise<UiCatalog>;

    export = loadUi;
}

declare module "@antora/asciidoc-loader" {
    import { Playbook, ContentCatalog, AntoraFile, AsciiDoctor } from "@antora/types";

    function loadAsciiDoc(file: AntoraFile, contentCatalog: ContentCatalog, config: AsciiDoctor.Config): AsciiDoctor.Document;

    namespace loadAsciiDoc {
        function resolveConfig(playbook?: Playbook): AsciiDoctor.Config;
    }

    export = loadAsciiDoc;
}

declare module "@antora/document-converter" {
    import { ContentCatalog, AsciiDoctor, AntoraFile } from "@antora/types";

    function convertDocuments(contentCatalog: ContentCatalog, asciidocConfig: AsciiDoctor.Config): Array<AntoraFile>;

    namespace convertDocuments {
        function convertDocument(file: AntoraFile, contentCatalog: ContentCatalog, asciidocConfig: AsciiDoctor.Config): AntoraFile;
    }

    export = convertDocuments;
}

declare module "@antora/navigation-builder" {
    import { ContentCatalog, AsciiDoctor, AntoraFile, NavigationCatalog } from "@antora/types";

    function buildNavigation(contentCatalog: ContentCatalog, asciidocConfig?: AsciiDoctor.Config): NavigationCatalog;

    export = buildNavigation;
}

declare module "@antora/page-composer" {
    import { Playbook, ContentCatalog, UiCatalog, Env, PageComposer, AntoraFile, NavigationCatalog } from "@antora/types";

    function createPageComposer(playbook: Playbook, contentCatalog: ContentCatalog, uiCatalog: UiCatalog, env?: Env): PageComposer;

    namespace createPageComposer {
        function buildSiteUiModel(playbook: Playbook, contentCatalog: ContentCatalog): PageComposer.SiteUiModel;
        function buildPageUiModel(
            file: AntoraFile,
            contentCatalog: ContentCatalog,
            navigationCatalog: NavigationCatalog,
            site: PageComposer.SiteUiModel
        ): PageComposer.PageUiModel;
        function buildUiModel(
            file: AntoraFile,
            contentCatalog: ContentCatalog,
            navigationCatalog: NavigationCatalog,
            site: PageComposer.SiteUiModel,
            env: Env
        ): PageComposer.UiModel;
    }

    export = createPageComposer;
}

declare module "@antora/site-mapper" {
    import { Playbook, AntoraFile } from "@antora/types";

    function mapSite(playbook: Playbook, pages: Array<AntoraFile>): Array<AntoraFile>;

    export = mapSite;
}

declare module "@antora/redirect-producer" {
    import { Playbook, ContentCatalog, AntoraFile } from "@antora/types";

    function produceRedirects(playbook: Playbook, contentCatalog: ContentCatalog): Array<AntoraFile>;

    export = produceRedirects;
}

declare module "@antora/site-publisher" {
    import { Playbook, Catalog, AntoraFile } from "@antora/types";

    function publishSite(playbook: Playbook, catalogs: Array<Catalog>): Promise<void>;

    export = publishSite;
}