diff --git a/terra-core/src/index.ts b/terra-core/src/index.ts index 9bc68e0..c5796e0 100644 --- a/terra-core/src/index.ts +++ b/terra-core/src/index.ts @@ -1,14 +1,34 @@ -// export * from "./app_root_path"; export * from './path_resolver'; export * from './testing_utils'; +/** + * Abstract representation of a AST node in terra. + * This interface serves as a base for node types and can be extended to + * represent various node-specific details and functionalities within terra. + */ export interface TerraNode {} +/** + * Class representing the result of a parsing operation. + * Contains an array of `TerraNode` objects. + */ export class ParseResult { nodes: TerraNode[] = []; } +/** + * Represents the context in which terra operates. + * Includes various directory paths and configuration flags. + */ export class TerraContext { + /** + * Constructs a new `TerraContext` instance. + * @param buildDir The build directory path. + * @param configDir The configuration directory path. + * @param outputDir The output directory path. + * @param clean Flag indicating whether to clean the build directory. + * @param verbose Flag for verbose logging. + */ constructor( public readonly buildDir: string = '', public readonly configDir: string = '', @@ -18,17 +38,39 @@ export class TerraContext { ) {} } +/** + * Type definition for a Parser function in terra. + * Transforms source code into AST nodes (TerraNode). + * This `Parser` can be part of a chain, where each `Parser` has the ability + * to modify the results of its predecessor before passing them to the next `Parser`. + * + * @param terraContext The `TerraContext` instance, providing operational context. + * @param args Additional arguments or data for parsing. + * @param parseResult An optional initial `ParseResult` from a previous Parser in the chain. + * @returns A new or modified `ParseResult` to be used by subsequent Parsers. + */ export type Parser = ( terraContext: TerraContext, args: any, parseResult?: ParseResult ) => ParseResult | undefined; +/** Interface representing the result of a rendering operation. */ export interface RenderResult { file_name: string; file_content: string; } +/** + * Type definition for a Renderer function in Terra. + * Processes the results obtained from a Parser. + * Use this Renderer to generate code or other forms of output based on the parsed AST nodes (TerraNode). + * + * @param terraContext The `TerraContext` instance, providing the operational context. + * @param args Additional arguments relevant to the rendering process. + * @param parseResult The `ParseResult` instance containing the Parser's output. + * @returns An array of `RenderResult` objects, representing the rendered output. + */ export type Renderer = ( terraContext: TerraContext, args: any, diff --git a/terra-core/src/path_resolver.ts b/terra-core/src/path_resolver.ts index 1ef33ce..50cee92 100644 --- a/terra-core/src/path_resolver.ts +++ b/terra-core/src/path_resolver.ts @@ -1,10 +1,15 @@ import fs from 'fs'; -import os from 'os'; import path from 'path'; /** - * Resolve the schema: `:`, or absolute path, or relative path + * Resolves a given path to its absolute form. + * It can resolve paths in various formats: module schemas (`:`), absolute paths, or relative paths. + * If the path is not absolute and `prefixDirIfNotAbsolute` is provided, the path is resolved relative to this directory. + * + * @param p The path to resolve, which can be in the format of a module schema, absolute, or relative path. + * @param prefixDirIfNotAbsolute The directory to use as a prefix for non-absolute paths. Defaults to an empty string. + * @returns The resolved absolute path. */ export function resolvePath( p: string, @@ -34,6 +39,13 @@ export function resolvePath( return path.resolve(localPathInModule); } +/** + * Resolves the path to a specified module. + * This function assumes the module exists in the `node_modules` directory relative to the current package's `package.json`. + * + * @param module The name of the module to resolve. + * @returns The resolved path of the module. + */ // TODO(littlegnal): Use `require.resolve(`${module}/package.json`)` to require the module's path export function resolveModulePath(module: string): string { let currentPackageJsonPath = process.env.npm_package_json; @@ -49,6 +61,13 @@ export function resolveModulePath(module: string): string { return path.resolve(parserPackageDir); } +/** + * Requires a module and returns its exported content. + * The module is expected to be located in the `node_modules` directory relative to the current package's `package.json`. + * + * @param module The name of the module to require. + * @returns The exported content of the required module. + */ // TODO(littlegnal): Use `require(`${module}/package.json`)` to require the module export function requireModule(module: string): any { let currentPackageJsonPath = process.env.npm_package_json; diff --git a/terra-core/src/testing_utils.ts b/terra-core/src/testing_utils.ts index 96f7f2e..db6dd87 100644 --- a/terra-core/src/testing_utils.ts +++ b/terra-core/src/testing_utils.ts @@ -34,4 +34,4 @@ export function visibleForTesting(module: any, ...func: Function[]): void { } } } -} \ No newline at end of file +}