@eagleoutice/flowr/documentation/wiki-mk/doc-maker.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { PathLike } from 'fs';
import type { GeneralDocContext } from './doc-context';
import type { RShell } from '../../r-bridge/shell';
import type { TreeSitterExecutor } from '../../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor';
import type { AsyncOrSync } from 'ts-essentials';
export interface DocMakerArgs {
    /** Overwrite existing wiki files, even if nothing changes */
    readonly force?: boolean;
    /**
     * The general documentation context to use for generating links and headers
     */
    readonly ctx: GeneralDocContext;
    /**
     * The RShell engine to use for R code execution and retrieval
     */
    readonly shell: RShell;
    /**
     * The TreeSitter engine to use for R code parsing
     */
    readonly treeSitter: TreeSitterExecutor;
}
export interface DocMakerOutputArgs {
    writeFileSync(path: PathLike, data: string): void;
    readFileSync(path: PathLike): string | Buffer<ArrayBufferLike> | undefined;
}
export declare enum WikiChangeType {
    Changed = 0,
    UnimportantChange = 1,
    Identical = 2
}
export interface DocMakerLike<Target extends string = string> {
    make(args: DocMakerArgs & DocMakerOutputArgs): Promise<boolean>;
    getTarget(): Target;
    getProducer(): string;
    getWrittenSubfiles(): Set<string>;
}
/**
 * Abstract base class for generating wiki files.
 * **Please make sure to register your WikiMaker implementation in the CLI wiki tool to have it executed:
 * `src/cli/wiki.ts`.**
 *
 * If this wiki page produces multiple pages ("sub files"), you can use `writeSubFile` inside the `text` method
 * to write those additional files.
 */
export declare abstract class DocMaker<Target extends string> implements DocMakerLike<Target> {
    private readonly target;
    private readonly filename;
    private readonly purpose;
    private readonly printHeader;
    private currentArgs?;
    private writtenSubfiles;
    /**
     * Creates a new WikiMaker instance.
     * @param target      - The target path where the wiki file will be generated.
     * @param filename    - The name of the file being generated. Probably use `module.filename`.
     * @param purpose     - The purpose of the file, e.g., 'wiki context for types'.
     * @param printHeader - Whether to print the auto-generation header. Default is `true`. Only mark this `false` if you plan to add it yourself.
     * @protected
     */
    protected constructor(target: Target, filename: string, purpose: string, printHeader?: boolean);
    /**
     * Gets the target path where the wiki file will be generated.
     */
    getTarget(): Target;
    /**
     * Gets the name of the producer of this wiki file.
     */
    getProducer(): string;
    /**
     * Gets the set of subfiles written during the last `make` call.
     */
    getWrittenSubfiles(): Set<string>;
    /**
     * Generates or updates the wiki file at the given target location.
     * @returns `true` if the file was created or updated, `false` if it was identical and not changed.
     */
    make(args: DocMakerArgs & DocMakerOutputArgs): Promise<boolean>;
    /**
     * Please note that for subfiles you have to always add your own header
     */
    protected writeSubFile(path: PathLike, data: string): boolean;
    /**
     * Normalizes the given wiki text for comparison.
     */
    protected normalizeText(text: string): string;
    /**
     * Determines the type of change between the old and new text.
     */
    protected didUpdate(path: PathLike, newText: string, oldText: string | undefined): WikiChangeType;
    /**
     * Generates the wiki text for the given arguments.
     * The text will be automatically prefixed with metadata including filename and purpose.
     */
    protected abstract text(args: DocMakerArgs): AsyncOrSync<string>;
}