@rvoh/psychic 3.0.1 → 3.0.2

package/dist/cjs/src/bin/helpers/printControllerHierarchy.js

@@ -0,0 +1,168 @@
+import colors from 'yoctocolors';
+import PsychicController from '../../controller/index.js';
+import PsychicApp from '../../psychic-app/index.js';
+const ROOT_CHILD_INDENT = 5;
+const MIN_DASHES = 2;
+export default function printControllerHierarchy(controllersPath) {
+    const lines = controllerHierarchyLines(controllersPath);
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+export function resolveControllerClasses(controllersPath) {
+    const psychicApp = PsychicApp.getOrFail();
+    const resolvedPath = controllersPath ?? psychicApp.paths.controllers;
+    const allControllers = psychicApp.controllers;
+    const controllerClasses = Object.values(allControllers).filter(ctrl => {
+        return ctrl.globalName.startsWith(globalPrefixFromPath(resolvedPath, psychicApp.paths.controllers));
+    });
+    return { controllerClasses, resolvedPath };
+}
+export function controllerHierarchyLines(controllersPath) {
+    const { controllerClasses, resolvedPath } = resolveControllerClasses(controllersPath);
+    const childrenMap = buildChildrenMap(controllerClasses);
+    const roots = controllerClasses.filter(ctrl => !controllerClasses.some(other => other !== ctrl && ctrl.prototype instanceof other));
+    if (roots.length === 0) {
+        return ['No controllers found.'];
+    }
+    const lines = [];
+    for (const root of roots) {
+        collectTreeLines(root, childrenMap, { depth: 0, displayColumn: 0, strippedPrefix: '', baseIndent: 0 }, lines, resolvedPath);
+    }
+    return lines;
+}
+export function controllerHierarchyViolations(controllersPath) {
+    const { controllerClasses, resolvedPath } = resolveControllerClasses(controllersPath);
+    const violations = [];
+    for (const ctrl of controllerClasses) {
+        const parentClass = Object.getPrototypeOf(ctrl);
+        if (parentClass === PsychicController)
+            continue;
+        const violation = hierarchyViolation(ctrl.globalName, parentClass.globalName, resolvedPath);
+        if (violation) {
+            violations.push(violation);
+        }
+    }
+    return violations;
+}
+export function buildChildrenMap(controllerClasses) {
+    const childrenMap = new Map();
+    for (const ctrl of controllerClasses) {
+        const parent = Object.getPrototypeOf(ctrl);
+        if (!childrenMap.has(parent)) {
+            childrenMap.set(parent, []);
+        }
+        childrenMap.get(parent).push(ctrl);
+    }
+    return childrenMap;
+}
+export function controllerTreeLine(displayedName, depth, displayColumn, baseIndent) {
+    if (depth === 0) {
+        return colors.cyan(displayedName);
+    }
+    const numDashes = Math.max(MIN_DASHES, displayColumn - baseIndent - 2);
+    const indentation = ' '.repeat(baseIndent);
+    const dashes = '─'.repeat(numDashes);
+    return `${indentation}└${dashes} ${colors.cyan(displayedName)}`;
+}
+/**
+ * Computes the actual column where the name starts on screen,
+ * accounting for MIN_DASHES potentially pushing the name further right.
+ */
+export function actualDisplayColumn(displayColumn, depth, baseIndent) {
+    if (depth === 0)
+        return displayColumn;
+    const numDashes = Math.max(MIN_DASHES, displayColumn - baseIndent - 2);
+    return baseIndent + numDashes + 2;
+}
+export function sharedDirPrefix(a, b) {
+    const aParts = a.split('/');
+    const bParts = b.split('/');
+    let shared = '';
+    for (let i = 0; i < Math.min(aParts.length, bParts.length); i++) {
+        if (aParts[i] === bParts[i]) {
+            shared += aParts[i] + '/';
+        }
+        else {
+            break;
+        }
+    }
+    return shared;
+}
+export function globalPrefixFromPath(path, defaultControllersPath) {
+    if (path === defaultControllersPath)
+        return 'controllers/';
+    const normalized = path.replace(/\/$/, '');
+    const defaultNormalized = defaultControllersPath.replace(/\/$/, '');
+    if (normalized.startsWith(defaultNormalized + '/')) {
+        const suffix = normalized.slice(defaultNormalized.length + 1);
+        return `controllers/${suffix}/`;
+    }
+    return 'controllers/';
+}
+/**
+ * Returns the directory portion of a globalName.
+ * e.g. "controllers/Admin/AuthedController" -> "controllers/Admin/"
+ *      "controllers/ApplicationController" -> "controllers/"
+ */
+export function globalNameDir(globalName) {
+    const lastSlash = globalName.lastIndexOf('/');
+    if (lastSlash === -1)
+        return '';
+    return globalName.slice(0, lastSlash + 1);
+}
+/**
+ * Returns the parent directory of a directory path.
+ * e.g. "controllers/Admin/" -> "controllers/"
+ *      "controllers/" -> ""
+ */
+export function parentOfDir(dir) {
+    const withoutTrailing = dir.slice(0, -1);
+    const lastSlash = withoutTrailing.lastIndexOf('/');
+    if (lastSlash === -1)
+        return '';
+    return withoutTrailing.slice(0, lastSlash + 1);
+}
+/**
+ * Checks whether a child controller violates the hierarchy convention.
+ * A controller should extend a controller in the same directory or the parent directory.
+ * Returns a warning message string if violated, or null if OK.
+ */
+export function hierarchyViolation(childGlobalName, parentGlobalName, controllersPath) {
+    const childDir = globalNameDir(childGlobalName);
+    const parentControllerDir = globalNameDir(parentGlobalName);
+    if (childDir === parentControllerDir || parentOfDir(childDir) === parentControllerDir) {
+        return null;
+    }
+    const childFilePath = controllersPath + '/' + childGlobalName.replace(/^controllers\//, '') + '.ts';
+    return `[hierarchy violation: ${childFilePath} should extend a BaseController at its same level]`;
+}
+function collectTreeLines(controller, childrenMap, { depth, displayColumn, strippedPrefix, baseIndent, }, lines, controllersPath) {
+    const displayedName = controller.globalName.slice(strippedPrefix.length);
+    lines.push(controllerTreeLine(displayedName, depth, displayColumn, baseIndent));
+    // The actual column where the name appears on screen (may differ from displayColumn
+    // when MIN_DASHES pushes the name further right)
+    const effectiveDisplayColumn = actualDisplayColumn(displayColumn, depth, baseIndent);
+    if (depth > 0) {
+        const parentClass = Object.getPrototypeOf(controller);
+        if (parentClass !== PsychicController) {
+            const violation = hierarchyViolation(controller.globalName, parentClass.globalName, controllersPath);
+            if (violation) {
+                const warningIndent = ' '.repeat(effectiveDisplayColumn);
+                lines.push(warningIndent + colors.yellow(violation));
+            }
+        }
+    }
+    const childBaseIndent = depth === 0 ? ROOT_CHILD_INDENT : effectiveDisplayColumn - 1;
+    const children = childrenMap.get(controller) ?? [];
+    for (const child of children) {
+        const shared = sharedDirPrefix(controller.globalName, child.globalName);
+        const childDisplayColumn = effectiveDisplayColumn + shared.length - strippedPrefix.length;
+        collectTreeLines(child, childrenMap, {
+            depth: depth + 1,
+            displayColumn: childDisplayColumn,
+            strippedPrefix: shared,
+            baseIndent: childBaseIndent,
+        }, lines, controllersPath);
+    }
+}

package/dist/cjs/src/bin/index.js

@@ -10,6 +10,7 @@ import PsychicApp from '../psychic-app/index.js';
 import enumsFileStr from './helpers/enumsFileStr.js';
 import generateRouteTypes from './helpers/generateRouteTypes.js';
 import { OpenApiSpecDiff } from './helpers/OpenApiSpecDiff.js';
+import printControllerHierarchy, { controllerHierarchyViolations, } from './helpers/printControllerHierarchy.js';
 import printRoutes from './helpers/printRoutes.js';
 export { BreakingChangesDetectedInOpenApiSpecError } from './helpers/OpenApiSpecDiff.js';
 export default class PsychicBin {
@@ -26,6 +27,12 @@ export default class PsychicBin {
     static printRoutes() {
         printRoutes();
     }
+    static printControllerHierarchy(controllersPath) {
+        printControllerHierarchy(controllersPath);
+    }
+    static controllerHierarchyViolations(controllersPath) {
+        return controllerHierarchyViolations(controllersPath);
+    }
     static async sync({ bypassDreamSync = false, schemaOnly = false, } = {}) {
         if (!bypassDreamSync)
             await DreamBin.sync(() => { }, { schemaOnly });

package/dist/cjs/src/cli/index.js

@@ -160,6 +160,31 @@ export default class PsychicCLI {
             await generateSyncOpenapiTypescriptInitializer(openapiFilepath, outfile, initializerName);
             process.exit();
         });
+        program
+            .command('inspect:controller-hierarchy')
+            .alias('i:controller-hierarchy')
+            .description('Displays the inheritance hierarchy of all PsychicController classes in the project.')
+            .argument('[path]', 'the controllers directory to scan (defaults to the configured controllers path)')
+            .action(async (controllersPath) => {
+            await initializePsychicApp();
+            PsychicBin.printControllerHierarchy(controllersPath);
+            process.exit();
+        });
+        program
+            .command('check:controller-hierarchy')
+            .description('Checks that all controllers extend a controller in the same or parent directory. Exits with an error if any violations are found.')
+            .argument('[path]', 'the controllers directory to scan (defaults to the configured controllers path)')
+            .action(async (controllersPath) => {
+            await initializePsychicApp();
+            const violations = PsychicBin.controllerHierarchyViolations(controllersPath);
+            if (violations.length > 0) {
+                for (const violation of violations) {
+                    console.error(violation);
+                }
+                process.exit(1);
+            }
+            process.exit();
+        });
         program
             .command('routes')
             .description('Prints a list of routes defined by the application, including path arguments and the controller/action reached by the route.')

package/dist/esm/src/bin/helpers/printControllerHierarchy.js

@@ -0,0 +1,168 @@
+import colors from 'yoctocolors';
+import PsychicController from '../../controller/index.js';
+import PsychicApp from '../../psychic-app/index.js';
+const ROOT_CHILD_INDENT = 5;
+const MIN_DASHES = 2;
+export default function printControllerHierarchy(controllersPath) {
+    const lines = controllerHierarchyLines(controllersPath);
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+export function resolveControllerClasses(controllersPath) {
+    const psychicApp = PsychicApp.getOrFail();
+    const resolvedPath = controllersPath ?? psychicApp.paths.controllers;
+    const allControllers = psychicApp.controllers;
+    const controllerClasses = Object.values(allControllers).filter(ctrl => {
+        return ctrl.globalName.startsWith(globalPrefixFromPath(resolvedPath, psychicApp.paths.controllers));
+    });
+    return { controllerClasses, resolvedPath };
+}
+export function controllerHierarchyLines(controllersPath) {
+    const { controllerClasses, resolvedPath } = resolveControllerClasses(controllersPath);
+    const childrenMap = buildChildrenMap(controllerClasses);
+    const roots = controllerClasses.filter(ctrl => !controllerClasses.some(other => other !== ctrl && ctrl.prototype instanceof other));
+    if (roots.length === 0) {
+        return ['No controllers found.'];
+    }
+    const lines = [];
+    for (const root of roots) {
+        collectTreeLines(root, childrenMap, { depth: 0, displayColumn: 0, strippedPrefix: '', baseIndent: 0 }, lines, resolvedPath);
+    }
+    return lines;
+}
+export function controllerHierarchyViolations(controllersPath) {
+    const { controllerClasses, resolvedPath } = resolveControllerClasses(controllersPath);
+    const violations = [];
+    for (const ctrl of controllerClasses) {
+        const parentClass = Object.getPrototypeOf(ctrl);
+        if (parentClass === PsychicController)
+            continue;
+        const violation = hierarchyViolation(ctrl.globalName, parentClass.globalName, resolvedPath);
+        if (violation) {
+            violations.push(violation);
+        }
+    }
+    return violations;
+}
+export function buildChildrenMap(controllerClasses) {
+    const childrenMap = new Map();
+    for (const ctrl of controllerClasses) {
+        const parent = Object.getPrototypeOf(ctrl);
+        if (!childrenMap.has(parent)) {
+            childrenMap.set(parent, []);
+        }
+        childrenMap.get(parent).push(ctrl);
+    }
+    return childrenMap;
+}
+export function controllerTreeLine(displayedName, depth, displayColumn, baseIndent) {
+    if (depth === 0) {
+        return colors.cyan(displayedName);
+    }
+    const numDashes = Math.max(MIN_DASHES, displayColumn - baseIndent - 2);
+    const indentation = ' '.repeat(baseIndent);
+    const dashes = '─'.repeat(numDashes);
+    return `${indentation}└${dashes} ${colors.cyan(displayedName)}`;
+}
+/**
+ * Computes the actual column where the name starts on screen,
+ * accounting for MIN_DASHES potentially pushing the name further right.
+ */
+export function actualDisplayColumn(displayColumn, depth, baseIndent) {
+    if (depth === 0)
+        return displayColumn;
+    const numDashes = Math.max(MIN_DASHES, displayColumn - baseIndent - 2);
+    return baseIndent + numDashes + 2;
+}
+export function sharedDirPrefix(a, b) {
+    const aParts = a.split('/');
+    const bParts = b.split('/');
+    let shared = '';
+    for (let i = 0; i < Math.min(aParts.length, bParts.length); i++) {
+        if (aParts[i] === bParts[i]) {
+            shared += aParts[i] + '/';
+        }
+        else {
+            break;
+        }
+    }
+    return shared;
+}
+export function globalPrefixFromPath(path, defaultControllersPath) {
+    if (path === defaultControllersPath)
+        return 'controllers/';
+    const normalized = path.replace(/\/$/, '');
+    const defaultNormalized = defaultControllersPath.replace(/\/$/, '');
+    if (normalized.startsWith(defaultNormalized + '/')) {
+        const suffix = normalized.slice(defaultNormalized.length + 1);
+        return `controllers/${suffix}/`;
+    }
+    return 'controllers/';
+}
+/**
+ * Returns the directory portion of a globalName.
+ * e.g. "controllers/Admin/AuthedController" -> "controllers/Admin/"
+ *      "controllers/ApplicationController" -> "controllers/"
+ */
+export function globalNameDir(globalName) {
+    const lastSlash = globalName.lastIndexOf('/');
+    if (lastSlash === -1)
+        return '';
+    return globalName.slice(0, lastSlash + 1);
+}
+/**
+ * Returns the parent directory of a directory path.
+ * e.g. "controllers/Admin/" -> "controllers/"
+ *      "controllers/" -> ""
+ */
+export function parentOfDir(dir) {
+    const withoutTrailing = dir.slice(0, -1);
+    const lastSlash = withoutTrailing.lastIndexOf('/');
+    if (lastSlash === -1)
+        return '';
+    return withoutTrailing.slice(0, lastSlash + 1);
+}
+/**
+ * Checks whether a child controller violates the hierarchy convention.
+ * A controller should extend a controller in the same directory or the parent directory.
+ * Returns a warning message string if violated, or null if OK.
+ */
+export function hierarchyViolation(childGlobalName, parentGlobalName, controllersPath) {
+    const childDir = globalNameDir(childGlobalName);
+    const parentControllerDir = globalNameDir(parentGlobalName);
+    if (childDir === parentControllerDir || parentOfDir(childDir) === parentControllerDir) {
+        return null;
+    }
+    const childFilePath = controllersPath + '/' + childGlobalName.replace(/^controllers\//, '') + '.ts';
+    return `[hierarchy violation: ${childFilePath} should extend a BaseController at its same level]`;
+}
+function collectTreeLines(controller, childrenMap, { depth, displayColumn, strippedPrefix, baseIndent, }, lines, controllersPath) {
+    const displayedName = controller.globalName.slice(strippedPrefix.length);
+    lines.push(controllerTreeLine(displayedName, depth, displayColumn, baseIndent));
+    // The actual column where the name appears on screen (may differ from displayColumn
+    // when MIN_DASHES pushes the name further right)
+    const effectiveDisplayColumn = actualDisplayColumn(displayColumn, depth, baseIndent);
+    if (depth > 0) {
+        const parentClass = Object.getPrototypeOf(controller);
+        if (parentClass !== PsychicController) {
+            const violation = hierarchyViolation(controller.globalName, parentClass.globalName, controllersPath);
+            if (violation) {
+                const warningIndent = ' '.repeat(effectiveDisplayColumn);
+                lines.push(warningIndent + colors.yellow(violation));
+            }
+        }
+    }
+    const childBaseIndent = depth === 0 ? ROOT_CHILD_INDENT : effectiveDisplayColumn - 1;
+    const children = childrenMap.get(controller) ?? [];
+    for (const child of children) {
+        const shared = sharedDirPrefix(controller.globalName, child.globalName);
+        const childDisplayColumn = effectiveDisplayColumn + shared.length - strippedPrefix.length;
+        collectTreeLines(child, childrenMap, {
+            depth: depth + 1,
+            displayColumn: childDisplayColumn,
+            strippedPrefix: shared,
+            baseIndent: childBaseIndent,
+        }, lines, controllersPath);
+    }
+}

package/dist/esm/src/bin/index.js

@@ -10,6 +10,7 @@ import PsychicApp from '../psychic-app/index.js';
 import enumsFileStr from './helpers/enumsFileStr.js';
 import generateRouteTypes from './helpers/generateRouteTypes.js';
 import { OpenApiSpecDiff } from './helpers/OpenApiSpecDiff.js';
+import printControllerHierarchy, { controllerHierarchyViolations, } from './helpers/printControllerHierarchy.js';
 import printRoutes from './helpers/printRoutes.js';
 export { BreakingChangesDetectedInOpenApiSpecError } from './helpers/OpenApiSpecDiff.js';
 export default class PsychicBin {
@@ -26,6 +27,12 @@ export default class PsychicBin {
     static printRoutes() {
         printRoutes();
     }
+    static printControllerHierarchy(controllersPath) {
+        printControllerHierarchy(controllersPath);
+    }
+    static controllerHierarchyViolations(controllersPath) {
+        return controllerHierarchyViolations(controllersPath);
+    }
     static async sync({ bypassDreamSync = false, schemaOnly = false, } = {}) {
         if (!bypassDreamSync)
             await DreamBin.sync(() => { }, { schemaOnly });

package/dist/esm/src/cli/index.js

@@ -160,6 +160,31 @@ export default class PsychicCLI {
             await generateSyncOpenapiTypescriptInitializer(openapiFilepath, outfile, initializerName);
             process.exit();
         });
+        program
+            .command('inspect:controller-hierarchy')
+            .alias('i:controller-hierarchy')
+            .description('Displays the inheritance hierarchy of all PsychicController classes in the project.')
+            .argument('[path]', 'the controllers directory to scan (defaults to the configured controllers path)')
+            .action(async (controllersPath) => {
+            await initializePsychicApp();
+            PsychicBin.printControllerHierarchy(controllersPath);
+            process.exit();
+        });
+        program
+            .command('check:controller-hierarchy')
+            .description('Checks that all controllers extend a controller in the same or parent directory. Exits with an error if any violations are found.')
+            .argument('[path]', 'the controllers directory to scan (defaults to the configured controllers path)')
+            .action(async (controllersPath) => {
+            await initializePsychicApp();
+            const violations = PsychicBin.controllerHierarchyViolations(controllersPath);
+            if (violations.length > 0) {
+                for (const violation of violations) {
+                    console.error(violation);
+                }
+                process.exit(1);
+            }
+            process.exit();
+        });
         program
             .command('routes')
             .description('Prints a list of routes defined by the application, including path arguments and the controller/action reached by the route.')

package/dist/types/src/bin/helpers/printControllerHierarchy.d.ts

@@ -0,0 +1,35 @@
+import PsychicController from '../../controller/index.js';
+export default function printControllerHierarchy(controllersPath?: string): void;
+export declare function resolveControllerClasses(controllersPath?: string): {
+    controllerClasses: (typeof PsychicController)[];
+    resolvedPath: string;
+};
+export declare function controllerHierarchyLines(controllersPath?: string): string[];
+export declare function controllerHierarchyViolations(controllersPath?: string): string[];
+export declare function buildChildrenMap(controllerClasses: (typeof PsychicController)[]): Map<typeof PsychicController, (typeof PsychicController)[]>;
+export declare function controllerTreeLine(displayedName: string, depth: number, displayColumn: number, baseIndent: number): string;
+/**
+ * Computes the actual column where the name starts on screen,
+ * accounting for MIN_DASHES potentially pushing the name further right.
+ */
+export declare function actualDisplayColumn(displayColumn: number, depth: number, baseIndent: number): number;
+export declare function sharedDirPrefix(a: string, b: string): string;
+export declare function globalPrefixFromPath(path: string, defaultControllersPath: string): string;
+/**
+ * Returns the directory portion of a globalName.
+ * e.g. "controllers/Admin/AuthedController" -> "controllers/Admin/"
+ *      "controllers/ApplicationController" -> "controllers/"
+ */
+export declare function globalNameDir(globalName: string): string;
+/**
+ * Returns the parent directory of a directory path.
+ * e.g. "controllers/Admin/" -> "controllers/"
+ *      "controllers/" -> ""
+ */
+export declare function parentOfDir(dir: string): string;
+/**
+ * Checks whether a child controller violates the hierarchy convention.
+ * A controller should extend a controller in the same directory or the parent directory.
+ * Returns a warning message string if violated, or null if OK.
+ */
+export declare function hierarchyViolation(childGlobalName: string, parentGlobalName: string, controllersPath: string): string | null;

package/dist/types/src/bin/index.d.ts

@@ -10,6 +10,8 @@ export default class PsychicBin {
         modelName?: string;
     }): Promise<void>;
     static printRoutes(): void;
+    static printControllerHierarchy(controllersPath?: string): void;
+    static controllerHierarchyViolations(controllersPath?: string): string[];
     static sync({ bypassDreamSync, schemaOnly, }?: {
         bypassDreamSync?: boolean;
         schemaOnly?: boolean;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "author": "RVOHealth",
   "repository": {
     "type": "git",