declapract/dist/domain/objects/FileCheckDeclaration.d.ts

A tool to declaratively define best practices, maintainable evolve them, and scalably enforce them.

import { DomainObject } from 'domain-objects';
import Joi from 'joi';
import { FileCheckContext } from './FileCheckContext';
import { ProjectCheckContext } from './ProjectCheckContext';
export declare enum FileCheckPurpose {
    BAD_PRACTICE = "BAD_PRACTICE",
    BEST_PRACTICE = "BEST_PRACTICE"
}
export declare enum FileCheckType {
    /**
     * simply checks that the file exists, without considering contents
     */
    EXISTS = "EXISTS",
    /**
     * checks that the file contents equal the declared contents
     *
     * e.g., `expect(foundContents).toEqual(declaredContents)`
     *
     * (default when file contents are declared)
     */
    EQUALS = "EQUALS",
    /**
     * check that the file contents contain the declared contents
     *
     * e.g., `expect(foundContents).toContain(declaredContents)`
     */
    CONTAINS = "CONTAINS",
    /**
     * check that the file contents satisfy a custom check function
     *
     * (default when the `.declapract.ts` file exports a `check` function)
     */
    CUSTOM = "CUSTOM"
}
export declare const isOfFileCheckType: import("type-fns").AssessWithAssure<string | number | symbol, FileCheckType>;
/**
 * a file check function is used to evaluate whether a file fails or passes a declaration
 *
 * a file check function either:
 * - returns successfully
 * - throws an error with the message containing the reason that the check failed
 *
 * for example
 * ```ts
 *   export const check = (contents: string | null) => expect(contents).toEqual(bestPracticeContents);
 * ```
 */
export type FileCheckFunction = (contents: string | null, context: FileCheckContext) => Promise<void> | void;
/**
 * a file fix function is used to automatically fix files that fail your declared practices
 *
 * a file fix function can declare:
 * - what the "fixed" file contents would be (including `null` to delete the file)
 * - what the "fixed" relative file path would be
 * - a combination of the above
 *
 * _note: it is **critical** that this function runs without mutating anything, as this function is run when planning even before the user requests to apply it. it should only declare **what** the final state would be, not actually do anything_
 */
export type FileFixFunction = (contents: string | null, context: FileCheckContext) => {
    relativeFilePath?: string;
    contents?: string | null;
} | Promise<{
    relativeFilePath?: string;
    contents?: string | null;
}>;
/**
 * a file contents function is used to dynamically define the best practice contents based on the context of the project
 *
 * for example
 * ```ts
 *   export const contents: FileContentsFunction = (context) => {
 *     if (context.projectPractices.includes('terraform')) return X
 *     else return Y
 *   }
 * ```
 */
export type FileContentsFunction = (context: ProjectCheckContext) => Promise<string> | string;
/**
 * a file check declaration is an object that defines how to check whether a file meets the declared criteria
 *
 * specifies which file and what to check for
 */
export interface FileCheckDeclaration {
    pathGlob: string;
    purpose: FileCheckPurpose;
    type: FileCheckType;
    required: boolean;
    check: FileCheckFunction;
    fix: FileFixFunction | null;
    contents: FileContentsFunction | null;
}
export declare class FileCheckDeclaration extends DomainObject<FileCheckDeclaration> implements FileCheckDeclaration {
    static schema: Joi.ObjectSchema<any>;
}