@rvoh/psychic 2.0.4 → 2.2.0

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

@@ -1,5 +1,5 @@
 import { DreamCLI } from '@rvoh/dream/system';
-import PsychicBin from '../bin/index.js';
+import PsychicBin, { BreakingChangesDetectedInOpenApiSpecError } from '../bin/index.js';
 import generateController from '../generate/controller.js';
 import generateSyncEnumsInitializer from '../generate/initializer/syncEnums.js';
 import generateSyncOpenapiTypescriptInitializer from '../generate/initializer/syncOpenapiTypescript.js';
@@ -196,6 +196,27 @@ export default class PsychicCLI {
             await PsychicBin.syncOpenapiJson();
             process.exit();
         });
+        program
+            .command('diff:openapi')
+            .description('compares the current branch open api spec file(s) with the main/master/head branch open api spec file(s)')
+            .option('-f', '--fail-on-breaking', 'fail on spec changes that are breaking')
+            .action(async (options) => {
+            await initializePsychicApp();
+            try {
+                PsychicBin.openapiDiff();
+            }
+            catch (error) {
+                if (error instanceof BreakingChangesDetectedInOpenApiSpecError) {
+                    if (options.failOnBreaking) {
+                        console.error(error.message);
+                        process.exit(1);
+                    }
+                }
+                else {
+                    throw error;
+                }
+            }
+        });
     }
     /**
      * @internal

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

@@ -131,7 +131,7 @@ export default class PsychicController {
     /**
      * @internal
      *
-     * Used for displaying routes when running `yarn psy routes`
+     * Used for displaying routes when running `pnpm psy routes`
      * cli command
      */
     static get disaplayName() {

package/dist/esm/src/devtools/helpers/launchDevServer.js

@@ -6,7 +6,7 @@ import UnexpectedUndefined from '../../error/UnexpectedUndefined.js';
 import PsychicApp from '../../psychic-app/index.js';
 const devServerProcesses = {};
 const debugEnabled = debuglog('psychic').enabled;
-export async function launchDevServer(key, { port = 3000, cmd = 'yarn client', timeout = 5000 } = {}) {
+export async function launchDevServer(key, { port = 3000, cmd = 'pnpm client', timeout = 5000 } = {}) {
     if (devServerProcesses[key])
         return;
     if (debugEnabled)

package/dist/esm/src/error/psychic-app/init-missing-package-manager.js

@@ -10,7 +10,7 @@ within conf/app.ts, you must have a call to "#set('packageManager', '<YOUR_CHOSE
 
   // conf/app.ts
   export default async (psy: PsychicApp) => {
-    psy.set('packageManager', 'yarn')
+    psy.set('packageManager', 'pnpm')
   }
     `;
     }

package/dist/esm/src/generate/helpers/generateResourceControllerSpecContent.js

@@ -87,8 +87,9 @@ function parseAttribute(attribute) {
     const [rawAttributeName, rawAttributeType, , enumValues] = attribute.split(':');
     if (!rawAttributeName || !rawAttributeType)
         return null;
+    const sanitizedAttrType = camelize(rawAttributeType)?.toLowerCase();
     // Handle belongs_to relationships
-    if (rawAttributeType === 'belongs_to') {
+    if (sanitizedAttrType === 'belongsto') {
         // For belongs_to relationships, convert "Ticketing/Ticket" to "ticket"
         const attributeName = camelize(rawAttributeName.split('/').pop());
         return { attributeName, attributeType: 'belongs_to', isArray: false, enumValues };
@@ -105,8 +106,9 @@ function parseAttribute(attribute) {
     return { attributeName, attributeType, isArray, enumValues };
 }
 function processAttributeByType({ attributeType, attributeName, isArray, enumValues, dotNotationVariable, fullyQualifiedModelName, attributeData, }) {
-    switch (attributeType) {
-        case 'belongs_to':
+    const sanitizedAttributeType = camelize(attributeType).toLowerCase();
+    switch (sanitizedAttributeType) {
+        case 'belongsto':
             // belongs_to relationships are NOT included in comparable attributes or create/update data
             // They are only tracked for original values in update contexts
             break;

package/dist/esm/src/generate/helpers/syncOpenapiTypescript/installOpenapiTypescript.js

@@ -8,7 +8,7 @@ export default async function installOpenapiTypescript() {
     try {
         await DreamCLI.spawn(cmd);
     }
-    catch (err) {
+    catch {
         console.log(`Failed to install openapi-typescript as a dev dependency. Please make sure the following command succeeds:
 
 "${cmd}"

package/dist/esm/src/openapi-renderer/SerializerOpenapiRenderer.js

@@ -298,6 +298,7 @@ function associationOpenapi(attribute, DataTypeForOpenapi, alreadyExtractedDesce
         if (associatedClass === undefined) {
             let serializerCheck;
             try {
+                // eslint-disable-next-line @typescript-eslint/no-unused-expressions
                 ;
                 DataTypeForOpenapi?.prototype?.serializers;
             }

package/dist/esm/src/openapi-renderer/app.js

@@ -57,7 +57,7 @@ export default class OpenapiAppRenderer {
             openapi: '3.1.0',
             info: {
                 version: openapiConfig?.info?.version || 'unknown version',
-                title: openapiConfig?.info?.title || 'unknown title',
+                title: openapiConfig?.info?.title || `${psychicApp.appName} | ${openapiName}`,
                 description: openapiConfig?.info?.description || 'The autogenerated openapi spec for your app',
             },
             paths: {},

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

@@ -0,0 +1,138 @@
+import type { DefaultPsychicOpenapiOptions } from '../../psychic-app/index.js';
+/**
+ * Interface to hold the result of a comparison
+ * between the current local OpenAPI specification and the head branch
+ * for a given OpenAPI file
+ */
+export interface ComparisonResult {
+    file: string;
+    hasChanges: boolean;
+    breaking: string[];
+    changelog: string[];
+    error?: string;
+}
+/**
+ * Interface to hold the configuration for oasdiff
+ */
+export interface OasDiffConfig {
+    command: string;
+    baseArgs: string[];
+    headBranch: string;
+}
+export type PsychicOpenapiConfig = DefaultPsychicOpenapiOptions;
+/**
+ * Class-based OpenAPI specification diff tool
+ *
+ * Compares current OpenAPI specs against the head branch using oasdiff
+ *
+ * Example usages:
+ *
+ * Instance-based usage
+ *    const diffTool = new OpenApiSpecDiff()
+ *    diffTool.compare(openapiConfigs)
+ *
+ * Factory method usage
+ *    const diffTool = OpenApiSpecDiff.create()
+ *    diffTool.compare(openapiConfigs)
+ *
+ * Static method usage (backward compatibility)
+ *    OpenApiSpecDiff.compare(openapiConfigs)
+ */
+export declare class OpenApiSpecDiff {
+    /**
+     * The configuration for the oasdiff command
+     */
+    private oasdiffConfig?;
+    /**
+     * Compares a list of OpenAPI specifications between the current branch and the head branch.
+     *
+     * Uses `oasdiff` under the hood to detect breaking and non-breaking changes for each file,
+     * helping you review and validate API updates with confidence before merging.
+     *
+     * This tool only runs for configurations where `checkDiffs` is enabled.
+     *
+     * @param openapiConfigs - An array of tuples containing the OpenAPI file name and its configuration.
+     * @example
+     * ```ts
+     * const openapiConfigs: [string, PsychicOpenapiConfig][] = [
+     *   ['openapi', { outputFilepath: 'openapi.json' }],
+     * ]
+     * OpenApiSpecDiff.compare(openapiConfigs)
+     * ```
+     */
+    compare(openapiConfigs: [string, PsychicOpenapiConfig][]): void;
+    /**
+     * Checks if oasdiff is installed locally
+     */
+    private hasOasDiffInstalled;
+    /**
+     * Fetch the head branch of a remote using git remote show origin
+     * default to main if not set
+     */
+    private getHeadBranch;
+    /**
+     * Validates that oasdiff is installed and builds the oasdiff config
+     */
+    private getOasDiffConfig;
+    /**
+     * Runs oasdiff command and returns the output
+     */
+    private runOasDiffCommand;
+    /**
+     * Compares two OpenAPI files using oasdiff
+     */
+    private compareSpecs;
+    /**
+     * Creates a temporary file path for the head branch content
+     */
+    private createTempFilePath;
+    /**
+     * Retrieves head branch content for a file
+     */
+    private getHeadBranchContent;
+    /**
+     * Compares a single OpenAPI file against head branch
+     */
+    private compareConfig;
+    /**
+     * Process and display the comparison results
+     */
+    private processResults;
+    /**
+     * Log error for a comparison result
+     */
+    private logError;
+    /**
+     * Log changes for a comparison result
+     */
+    private logChanges;
+    /**
+     * Log breaking changes for a comparison result
+     */
+    private logBreakingChanges;
+    /**
+     * Log changelog for a comparison result
+     */
+    private logChangelog;
+    /**
+     * Log no changes for a comparison result
+     */
+    private logNoChanges;
+    /**
+     * Log final summary and handle exit conditions
+     */
+    private logSummary;
+    /**
+     * Static factory method for convenience
+     */
+    static create(): OpenApiSpecDiff;
+    /**
+     * Static method to maintain compatibility with functional approach
+     */
+    static compare(openapiConfigs: [string, PsychicOpenapiConfig][]): void;
+}
+export declare class BreakingChangesDetectedInOpenApiSpecError extends Error {
+    private readonly oasdiffConfig;
+    constructor(oasdiffConfig: OasDiffConfig);
+    get message(): string;
+}

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

@@ -1,3 +1,4 @@
+export { BreakingChangesDetectedInOpenApiSpecError } from './helpers/OpenApiSpecDiff.js';
 export default class PsychicBin {
     static generateController(controllerName: string, actions: string[]): Promise<void>;
     static generateResource(route: string, fullyQualifiedModelName: string, columnsWithTypes: string[], options: {
@@ -13,7 +14,8 @@ export default class PsychicBin {
         schemaOnly?: boolean;
     }): Promise<void>;
     static postSync(): Promise<void>;
-    static syncTypes(customTypes?: any): Promise<void>;
+    static syncTypes(): Promise<void>;
+    static openapiDiff(): void;
     static syncOpenapiTypescriptFiles(): Promise<void>;
     static syncOpenapiJson(): Promise<void>;
     static syncRoutes(): Promise<void>;

package/dist/types/src/cli/helpers/ASTBuilder.d.ts

@@ -0,0 +1,89 @@
+import ts from 'typescript';
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    protected newLine(): ts.Identifier;
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    protected getPropertyFromInterface(interfaceNode: ts.InterfaceDeclaration, propertyName: string): ts.PropertySignature | null;
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    protected extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias: ts.TypeAliasDeclaration): (ts.LiteralTypeNode & {
+        literal: {
+            text: string;
+        };
+    })[];
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    protected extractTypeNodesFromTypeOrUnion(typeAlias: ts.TypeAliasDeclaration | ts.PropertySignature): ts.TypeNode[];
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    protected exportedTypeAliasOrNull(node: ts.Node, exportName?: string): ts.TypeAliasDeclaration | null;
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    protected exportedInterfaceOrNull(node: ts.Node, exportName?: string): ts.InterfaceDeclaration | null;
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    protected psychicTypesPath(): string;
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    protected prettier(output: string): Promise<string>;
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    protected getFirstGenericType(node: ts.Node): ts.TypeNode | null;
+}

package/dist/types/src/cli/helpers/ASTPsychicTypesBuilder.d.ts

@@ -0,0 +1,28 @@
+import ASTBuilder from './ASTBuilder.js';
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTPsychicTypesBuilder extends ASTBuilder {
+    build(): Promise<void>;
+    /**
+     * @internal
+     *
+     * builds up the `export const psychicTypes = ...` statement within the types/psychic.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    private buildPsychicTypes;
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    private printStatements;
+}

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

@@ -76,7 +76,7 @@ export default class PsychicController {
     /**
      * @internal
      *
-     * Used for displaying routes when running `yarn psy routes`
+     * Used for displaying routes when running `pnpm psy routes`
      * cli command
      */
     static get disaplayName(): string;

package/dist/types/src/psychic-app/index.d.ts

@@ -491,6 +491,34 @@ interface PsychicOpenapiBaseOptions {
      * ```
      */
     validate?: OpenapiValidateOption;
+    /**
+     * Enables automatic comparison of OpenAPI specifications between the current
+     * working branch and the main/master/head branch.
+     *
+     * When set to `true`, Psychic will perform a diff check between the OpenAPI spec
+     * in the current branch and the one in the main/master/head branch. This is done using the
+     * `OpenApiSpecDiff` tool, which analyzes structural and semantic differences
+     * between the two specs.
+     *
+     * This feature is useful for catching unintended changes to your API contract
+     * before they are merged, especially breaking changes that could affect downstream
+     * consumers or integrations.
+     *
+     * Typical use cases include CI/CD validation, pull request checks, or local
+     * development sanity checks.
+     *
+     * Example usage:
+     * ```ts
+     * psy.set('openapi', {
+     *   ...
+     *   checkDiffs: true,
+     *   ...
+     * });
+     * ```
+     *
+  
+     */
+    checkDiffs?: boolean;
 }
 interface PsychicOpenapiInfo {
     version: string;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "author": "RVOHealth",
   "repository": {
     "type": "git",
@@ -48,28 +48,29 @@
     "dist/**/*"
   ],
   "scripts": {
-    "client": "yarn --cwd=./client start",
-    "client:fspec": "VITE_PSYCHIC_ENV=test BROWSER=none yarn --cwd=./client start",
-    "psy": "NODE_ENV=${NODE_ENV:-test} yarn psyts",
+    "client": "cd client && pnpm start",
+    "client:fspec": "cd client && VITE_PSYCHIC_ENV=test BROWSER=none pnpm start",
+    "psy": "NODE_ENV=${NODE_ENV:-test} pnpm psyts",
     "psyjs": "node ./dist/test-app/src/cli/index.js",
     "psyts": "NODE_ENV=${NODE_ENV:-test} tsx ./test-app/src/cli/index.ts",
     "gpsy": "tsx ./global-cli/main.ts",
     "build": "echo \"building cjs...\" && rm -rf dist && npx tsc -p ./tsconfig.cjs.build.json && echo \"building esm...\" && npx tsc -p ./tsconfig.esm.build.json",
     "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && npx tsc -p ./tsconfig.esm.build.test-app.json && echo \"building test app to cjs...\" && npx tsc -p ./tsconfig.cjs.build.test-app.json",
-    "types:esm:trace": "rm -rf dist && npx tsc -p ./tsconfig.esm.build.json --generateTrace ./typetrace --diagnostics && yarn analyze-trace ./typetrace --skipMillis 100 --forceMillis 300",
+    "types:esm:trace": "rm -rf dist && npx tsc -p ./tsconfig.esm.build.json --generateTrace ./typetrace --diagnostics && pnpm analyze-trace ./typetrace --skipMillis 100 --forceMillis 300",
     "dev": "nodemon --quiet --no-stdin",
     "console": "tsx ./test-app/src/conf/repl.ts",
     "uspec": "vitest --config ./spec/unit/vite.config.ts",
     "fspec": "vitest run --config=./spec/features/vite.config.ts",
-    "format": "yarn run prettier . --write",
-    "lint": "yarn run eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\" \"test-app/**/*.ts\" && yarn run prettier . --check",
-    "prepack": "yarn build"
+    "format": "pnpm prettier . --write",
+    "lint": "pnpm eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\" \"test-app/**/*.ts\" && pnpm prettier . --check",
+    "prepack": "pnpm build"
   },
   "dependencies": {
     "@types/cookie-parser": "^1.4.8",
     "@types/cors": "^2.8.17",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "body-parser": "^2.2.1",
     "commander": "^12.1.0",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
@@ -81,29 +82,31 @@
     "@rvoh/dream": "^2.0.3",
     "@types/express": "^5.0.1",
     "commander": "^12.1.0",
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "openapi-typescript": "^7.8.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.19.0",
+    "@eslint/js": "^9.39.1",
     "@jest-mock/express": "^3.0.0",
     "@rvoh/dream": "^2.0.3",
     "@rvoh/dream-spec-helpers": "^2.0.0",
     "@rvoh/psychic-spec-helpers": "^2.0.0",
-    "@types/express": "^5.0.1",
+    "@types/body-parser": "^1.19.6",
+    "@types/express": "^5.0.6",
     "@types/express-session": "^1.18.2",
     "@types/node": "^22.17.1",
     "@types/passport": "^0",
     "@types/passport-local": "^1",
     "@types/pg": "^8.11.8",
     "@types/supertest": "^6.0.3",
+    "@typescript-eslint/parser": "^8.48.1",
     "@typescript/analyze-trace": "^0.10.1",
-    "eslint": "^9.19.0",
-    "express": "^5.1.0",
+    "eslint": "^9.39.1",
+    "express": "^5.2.1",
     "express-session": "^1.18.2",
     "jsdom": "^26.1.0",
     "kysely": "^0.28.5",
-    "kysely-codegen": "~0.17.0",
+    "kysely-codegen": "~0.19.0",
     "luxon-jest-matchers": "^0.1.14",
     "nodemon": "^3.1.11",
     "openapi-typescript": "^7.8.0",
@@ -117,9 +120,9 @@
     "tsx": "^4.19.3",
     "typedoc": "^0.26.6",
     "typescript": "^5.5.4",
-    "typescript-eslint": "=7.18.0",
+    "typescript-eslint": "^8.48.1",
     "vitest": "^4.0.9",
     "winston": "^3.14.2"
   },
-  "packageManager": "yarn@4.7.0"
+  "packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a"
 }

package/dist/cjs/src/cli/helpers/TypesBuilder.js

@@ -1,23 +0,0 @@
-import { DreamApp } from '@rvoh/dream';
-import { CliFileWriter } from '@rvoh/dream/system';
-import * as path from 'node:path';
-import PsychicApp from '../../psychic-app/index.js';
-export default class TypesBuilder {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static async sync(customTypes = undefined) {
-        const dreamApp = DreamApp.getOrFail();
-        const schemaPath = path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
-        await CliFileWriter.write(schemaPath, this.build(customTypes));
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static build(customTypes = undefined) {
-        const psychicApp = PsychicApp.getOrFail();
-        const output = {
-            openapiNames: Object.keys(psychicApp.openapi),
-            ...(customTypes || {}),
-        };
-        return `const psychicTypes = ${JSON.stringify(output, null, 2)} as const
-
-export default psychicTypes`;
-    }
-}

package/dist/esm/src/cli/helpers/TypesBuilder.js

@@ -1,23 +0,0 @@
-import { DreamApp } from '@rvoh/dream';
-import { CliFileWriter } from '@rvoh/dream/system';
-import * as path from 'node:path';
-import PsychicApp from '../../psychic-app/index.js';
-export default class TypesBuilder {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static async sync(customTypes = undefined) {
-        const dreamApp = DreamApp.getOrFail();
-        const schemaPath = path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
-        await CliFileWriter.write(schemaPath, this.build(customTypes));
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static build(customTypes = undefined) {
-        const psychicApp = PsychicApp.getOrFail();
-        const output = {
-            openapiNames: Object.keys(psychicApp.openapi),
-            ...(customTypes || {}),
-        };
-        return `const psychicTypes = ${JSON.stringify(output, null, 2)} as const
-
-export default psychicTypes`;
-    }
-}

package/dist/types/src/cli/helpers/TypesBuilder.d.ts

@@ -1,7 +0,0 @@
-export default class TypesBuilder {
-    static sync(customTypes?: any): Promise<void>;
-    static build(customTypes?: any): string;
-}
-export interface PsychicTypeSync {
-    openapiNames: string[];
-}