@groton/canvas-api.swagger-renderer 0.1.0

package/dist/Render/Overrides.js

@@ -0,0 +1,138 @@
+import { Colors } from '@battis/qui-cli.colors';
+import { Log } from '@battis/qui-cli.log';
+import path from 'node:path';
+let _overrides = {};
+let _outputPath = undefined;
+export function setOverrides(overrides) {
+    _overrides = overrides;
+    for (const tsReference of _overrides.tsReferences || []) {
+        if (tsReference.filePath) {
+            tsReference.filePath = path.resolve(outputPath(), tsReference.filePath);
+        }
+    }
+    for (const name in _overrides.tsTypes) {
+        for (const ref of _overrides.tsTypes[name].tsReferences || []) {
+            if (ref.filePath) {
+                ref.filePath = path.resolve(outputPath(), ref.filePath);
+            }
+        }
+    }
+    for (const nickname in _overrides.operations) {
+        for (const ref of _overrides.operations[nickname].tsType?.tsReferences ||
+            []) {
+            if (ref.filePath) {
+                ref.filePath = path.resolve(outputPath(), ref.filePath);
+            }
+        }
+        for (const tsImport of _overrides.operations[nickname].tsImports || []) {
+            if (tsImport.filePath) {
+                tsImport.filePath = path.resolve(outputPath(), tsImport.filePath);
+            }
+        }
+        for (const paramType of [
+            'tsPathParameters',
+            'tsQueryParameters',
+            'tsFormParameters',
+            'tsBodyParameters'
+        ]) {
+            // @ts-expect-error 7053 not gonna deal with _that_ type
+            for (const param of _overrides.operations[nickname][paramType] || []) {
+                if (param.tsType.tsReference?.filePath) {
+                    param.tsType.tsReference.filePath = path.resolve(outputPath(), param.tsType.tsReference.filePath);
+                }
+            }
+        }
+    }
+}
+export function setOutputPath(outputPath) {
+    _outputPath = outputPath;
+}
+function outputPath() {
+    if (!_outputPath) {
+        throw new Error(`Overrides outputPath accessed before being initialized`);
+    }
+    return _outputPath;
+}
+export function tsReference(type) {
+    return _overrides.tsReferences?.find((ref) => ref.type === type);
+}
+export function tsType(type) {
+    let result = undefined;
+    if (_overrides.tsTypes && _overrides.tsTypes[type]) {
+        result = { description: type, ..._overrides.tsTypes[type] };
+        Log.debug(`Overriding ${Colors.value('type')} ${Colors.quotedValue(`"${type}"`)} as ${Colors.value(result.type)}`);
+    }
+    return result;
+}
+export function operation(operation) {
+    if (_overrides.operations && _overrides.operations[operation.nickname]) {
+        const override = _overrides.operations[operation.nickname];
+        Log.debug(`Overriding operation ${Colors.value(operation.nickname)} properties ${Object.getOwnPropertyNames(override)
+            .filter((p) => typeof p !== 'number')
+            .map(Colors.value)
+            .join(', ')}`);
+        const result = merge(operation, _overrides.operations[operation.nickname]);
+        for (const paramType of [
+            'tsPathParameters',
+            'tsQueryParameters',
+            'tsFormParameters',
+            'tsBodyParameters'
+        ]) {
+            if (paramType in result) {
+                // @ts-expect-error 7053 TODO paramType typing
+                result[paramType] = result[paramType].reduce((params, param) => {
+                    const i = params.findIndex((p) => p.tsName === param.tsName);
+                    if (i >= 0) {
+                        params[i] = param;
+                    }
+                    else {
+                        params.push(param);
+                    }
+                    return params;
+                }, []);
+            }
+        }
+        return result;
+    }
+    return operation;
+}
+function merge(a, b) {
+    if (a !== undefined && a !== null && b !== undefined && b !== null) {
+        if (Array.isArray(a)) {
+            if (Array.isArray(b)) {
+                return [...a, ...b];
+            }
+            else {
+                throw new TypeError(`Type mismatch, trying to merge ${typeof b} into an array.`);
+            }
+        }
+        else if (typeof a === 'object') {
+            if (typeof b === 'object') {
+                const result = {};
+                let key;
+                for (key of [
+                    ...Array.from(new Set([
+                        ...Object.getOwnPropertyNames(a),
+                        ...Object.getOwnPropertyNames(b)
+                    ]))
+                ]) {
+                    // @ts-expect-error 2322 TODO setting previously unset property
+                    result[key] = merge(a[key], b[key]);
+                }
+                return result;
+            }
+            else {
+                throw new TypeError(`Type mismatch, trying to merge ${typeof b} into an object.`);
+            }
+        }
+        else {
+            if (typeof a === typeof b) {
+                return b;
+            }
+            else {
+                throw new TypeError(`Type mismatch, trying to replace ${typeof a} with ${typeof b}`);
+            }
+        }
+    }
+    return (b || a);
+}

package/dist/Render/Render.d.ts

@@ -0,0 +1,19 @@
+import { PathString } from '@battis/descriptive-types';
+import * as Plugin from '@battis/qui-cli.plugin';
+type Configuration = Plugin.Configuration & {
+    specPath?: PathString;
+    overridePath?: PathString;
+    templatePath?: PathString;
+    outputPath?: PathString;
+    modelDirName?: string;
+    operationsDirName?: string;
+    prettierConfigPath?: PathString;
+    map?: boolean;
+};
+export declare const name = "render";
+export declare const src: string;
+export declare function configure(config?: Configuration): void;
+export declare function options(): Plugin.Options;
+export declare function init(args: Plugin.ExpectedArguments<typeof options>): void;
+export declare function run(results?: Plugin.AccumulatedResults): Promise<void>;
+export {};

package/dist/Render/Render.js

@@ -0,0 +1,124 @@
+import { Colors } from '@battis/qui-cli.colors';
+import { Log } from '@battis/qui-cli.log';
+import * as Plugin from '@battis/qui-cli.plugin';
+import { Root } from '@battis/qui-cli.root';
+import fs from 'node:fs';
+import path from 'node:path';
+import ora from 'ora';
+import * as Download from '../Download.js';
+import * as Models from './Models.js';
+import * as Operations from './Operations.js';
+import * as Overrides from './Overrides.js';
+Root.configure({ root: process.cwd() });
+export const name = 'render';
+export const src = path.dirname(import.meta.dirname);
+let specPath = './spec';
+let overridePath;
+let templatePath = path.resolve(import.meta.dirname, '../../templates');
+let outputPath = './src';
+let modelDirName = 'Resources';
+let operationsDirName = 'Endpoints';
+let prettierConfigPath = './.prettierrc.json';
+let map = false;
+export function configure(config = {}) {
+    specPath = Plugin.hydrate(config.specPath, specPath);
+    overridePath = Plugin.hydrate(config.overridePath, overridePath);
+    templatePath = Plugin.hydrate(config.templatePath, templatePath);
+    outputPath = Plugin.hydrate(config.outputPath, outputPath);
+    modelDirName = Plugin.hydrate(config.modelDirName, modelDirName);
+    operationsDirName = Plugin.hydrate(config.operationsDirName, operationsDirName);
+    prettierConfigPath = Plugin.hydrate(config.prettierConfigPath, prettierConfigPath);
+    map = Plugin.hydrate(config.map, map);
+}
+export function options() {
+    return {
+        flag: {
+            map: {
+                description: `Output the annotated code map (default: ${Colors.value(map)})`,
+                default: map
+            }
+        },
+        opt: {
+            specPath: {
+                description: `Path to Swagger spec file or directory (default: ${Colors.url(specPath)})`,
+                default: specPath
+            },
+            overridePath: {
+                description: `Path to TypeScript types override JSON file (default: ${Colors.url(overridePath)})`,
+                default: overridePath
+            },
+            templatePath: {
+                description: `Path to Handlebars template directory (default: ${Colors.url(templatePath)})`,
+                default: templatePath
+            },
+            outputPath: {
+                description: `Path to output directory (default: ${Colors.url(outputPath)})`,
+                default: outputPath
+            },
+            modelDirName: {
+                description: `Name of resource definitions directory (default: ${Colors.quotedValue(`"${modelDirName}"`)})`,
+                default: modelDirName
+            },
+            operationsDirName: {
+                description: `Name of endpoint definitions directory (default: ${Colors.quotedValue(`"${operationsDirName}"`)})`,
+                default: operationsDirName
+            }
+        }
+    };
+}
+export function init(args) {
+    configure(args.values);
+}
+export async function run(results) {
+    const spinner = ora(`Looking for specs`).start();
+    let specPaths = undefined;
+    specPath = path.resolve(Root.path(), specPath);
+    if (results && results[Download.name]) {
+        specPaths = results[Download.name];
+        spinner.text = `Using specs provided by download`;
+    }
+    else if (fs.lstatSync(specPath).isDirectory()) {
+        specPaths = fs
+            .readdirSync(specPath)
+            .filter((fileName) => !fileName.startsWith('.'))
+            .map((fileName) => path.join(specPath, fileName));
+        spinner.text = `Using specs found in directory ${Colors.url(specPath)}`;
+    }
+    else {
+        specPaths = [specPath];
+        spinner.text = `Using spec file ${Colors.url(specPath)}}`;
+    }
+    if (!specPaths) {
+        spinner.fail(`No specs found`);
+        throw new Error('No specPaths defined or received from Downloads');
+    }
+    spinner.succeed(`Loaded specs`);
+    templatePath = path.resolve(Root.path(), templatePath);
+    Log.info(`Templates will be read from ${Colors.url(templatePath)}`);
+    outputPath = path.resolve(Root.path(), outputPath);
+    Log.info(`Rendered TypeScript files will be written to ${Colors.url(outputPath)}`);
+    spinner.start(`Checking for overrides`);
+    Overrides.setOutputPath(outputPath);
+    if (overridePath) {
+        overridePath = path.resolve(Root.path(), overridePath);
+        Overrides.setOverrides(JSON.parse(fs.readFileSync(overridePath).toString()));
+        spinner.succeed(`Overrides loaded from ${Colors.url(overridePath)}`);
+    }
+    else {
+        spinner.info(`No overrides`);
+    }
+    const { spec, models } = await Models.generate({
+        specPaths,
+        templatePath,
+        outputPath: path.join(outputPath, modelDirName)
+    });
+    const operations = await Operations.generate({
+        spec,
+        models,
+        templatePath,
+        outputPath: path.join(outputPath, operationsDirName)
+    });
+    if (map) {
+        fs.writeFileSync(path.join(outputPath, 'map.json'), JSON.stringify(operations, null, 2));
+    }
+}

package/dist/Render/TSAnnotation.d.ts

@@ -0,0 +1,19 @@
+import { PathString } from '@battis/descriptive-types';
+export type TSDeprecation = string | undefined;
+export type TSExport = 'export' | '' | undefined;
+export type TSName = string;
+export type TSType = {
+    type: string;
+    tsReferences?: TSReference[];
+    optional?: '?';
+    description?: string;
+};
+export type TSReference = {
+    type: string;
+} & ({
+    filePath?: PathString;
+    packagePath?: never;
+} | {
+    packagePath: string;
+    filePath?: never;
+});

package/dist/Render/TSAnnotation.js

@@ -0,0 +1 @@
+export {};

package/dist/Render/TypeScript.d.ts

@@ -0,0 +1,10 @@
+import { PathString } from '@battis/descriptive-types';
+import * as Swagger from '@groton/swagger-spec-ts';
+import { AnnotatedModel } from './Annotation.js';
+import { TSDeprecation, TSExport, TSName, TSType } from './TSAnnotation.js';
+export declare function toTSDeprecation(obj: object): TSDeprecation;
+export declare function toTSExport(_: AnnotatedModel): TSExport;
+export declare function toTSPropertyName(id: string): TSName;
+export declare function toTSTypeName(id: string): TSName;
+export declare function toTSNamespace(filePath: PathString): TSName;
+export declare function toTSType(property: Swagger.v1p2.DataType): TSType;

package/dist/Render/TypeScript.js

@@ -0,0 +1,84 @@
+import { Colors } from '@battis/qui-cli.colors';
+import { Log } from '@battis/qui-cli.log';
+import * as Swagger from '@groton/swagger-spec-ts';
+import path from 'node:path';
+import * as Overrides from './Overrides.js';
+export function toTSDeprecation(obj) {
+    if ('deprecated' in obj && obj.deprecated) {
+        return `@deprecated ${'deprecation_description' in obj ? obj.deprecation_description : ''}`;
+    }
+    return undefined;
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function toTSExport(_) {
+    return 'export';
+}
+export function toTSPropertyName(id) {
+    if (/^[a-z_$][a-z_$0-9]*$/i.test(id)) {
+        return id;
+    }
+    return `"${id}"`;
+}
+export function toTSTypeName(id) {
+    return id.replace(/[^a-z0-9_]+/gi, '');
+}
+export function toTSNamespace(filePath) {
+    let tsNamespace = path
+        .basename(filePath, '.ts')
+        .replace(/[^a-z0-9_]+/gi, '_')
+        .split('_')
+        .map((token) => token.length ? token[0].toUpperCase() + token.slice(1) : '')
+        .join('');
+    if (tsNamespace === 'V1') {
+        tsNamespace = tsNamespace.toLowerCase();
+    }
+    return tsNamespace;
+}
+export function toTSType(property) {
+    if (Swagger.v1p2.isRefType(property)) {
+        return {
+            type: toTSTypeName(property.$ref),
+            tsReferences: [{ type: toTSTypeName(property.$ref) }]
+        };
+    }
+    let tsType = Overrides.tsType(property.type);
+    if (!tsType) {
+        tsType = { type: 'unknown' };
+        switch (property.type) {
+            case 'boolean':
+            case 'number':
+                tsType.description = `type: ${property.type}`;
+                tsType.type = `${property.type} | string`;
+                break;
+            case 'void':
+            case 'string':
+                tsType.type = property.type;
+                break;
+            case 'integer':
+                tsType.type = 'number | string';
+                tsType.description = `type: ${property.type}`;
+                break;
+            case 'array':
+                if ('items' in property) {
+                    if ('$ref' in property.items && property.items.$ref === 'Array') {
+                        tsType.type = 'string[]';
+                        Log.debug(`Interpretting an array with ${Colors.value('items.$ref')}: ${Colors.quotedValue(`"Array"`)} as ${Colors.value(tsType.type)}`);
+                        break;
+                    }
+                    else {
+                        const itemType = toTSType(property.items);
+                        tsType.type = `${itemType.type}[]`;
+                        tsType.tsReferences = itemType.tsReferences;
+                    }
+                }
+                break;
+            default:
+                Log.debug(`Interpretting ${Colors.value('type')}: ${Colors.quotedValue(`"${property.type}"`)} as  ${Colors.value('RefType')}`);
+                return toTSType({ $ref: property.type });
+        }
+    }
+    if ('format' in property && property.format != null) {
+        tsType.description = `${tsType.description || ''}\n\nformat: '${property.format}'`;
+    }
+    return tsType;
+}

package/dist/Render/importPath.d.ts

@@ -0,0 +1,2 @@
+import { PathString } from '@battis/descriptive-types';
+export declare function importPath(from: PathString, to: PathString): string;

package/dist/Render/importPath.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+export function importPath(from, to) {
+    let relative = path.relative(path.dirname(from), to);
+    if (!/\//.test(relative)) {
+        relative = `./${relative}`;
+    }
+    relative = relative.replace(/\.ts$/, '.js');
+    return relative;
+}

package/dist/Render/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Render/index.js

@@ -0,0 +1,5 @@
+import { Core } from '@battis/qui-cli.core';
+import { register } from '@battis/qui-cli.plugin';
+import * as Render from './Render.js';
+await register(Render);
+await Core.run();

package/dist/Render/writePrettier.d.ts

@@ -0,0 +1,2 @@
+import { PathString } from '@battis/descriptive-types';
+export declare function writePrettier(filepath: PathString, content: string): Promise<void>;

package/dist/Render/writePrettier.js

@@ -0,0 +1,25 @@
+import { Colors } from '@battis/qui-cli.colors';
+import { Log } from '@battis/qui-cli.log';
+import { Root } from '@battis/qui-cli.root';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as prettier from 'prettier';
+export async function writePrettier(filepath, content) {
+    filepath = path.resolve(Root.path(), filepath);
+    const dir = path.dirname(filepath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    try {
+        fs.writeFileSync(filepath, content);
+        fs.writeFileSync(filepath, await prettier.format(content, {
+            filepath,
+            parser: 'typescript',
+            ...(await prettier.resolveConfig(filepath))
+        }));
+    }
+    catch (error) {
+        Log.error(`Error making ${Colors.url(filepath)} prettier: ${error.message}`, { prettierConfig: await prettier.resolveConfig(filepath) });
+        fs.writeFileSync(filepath, content);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,5 @@
+import { build } from '@battis/qui-cli.structured';
+await build({
+    fileName: import.meta.filename,
+    commandName: 'swagger-renderer'
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@groton/canvas-api.swagger-renderer",
+  "version": "0.1.0",
+  "description": "Render Canvas LMS Swagger 1.0 API documentation as TypeScript client",
+  "homepage": "https://github.com/groton-school/canvas-cli/tree/main/packages/api/swagger-renderer#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/groton-school/canvas-cli.git",
+    "directory": "packages/api/swagger-renderer"
+  },
+  "author": {
+    "name": "Seth Battis",
+    "email": "sbattis@groton.org"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "directories": {
+    "bin": "./bin"
+  },
+  "dependencies": {
+    "@battis/qui-cli.colors": "^2.1.0",
+    "@battis/qui-cli.core": "^3.1.0",
+    "@battis/qui-cli.log": "^2.2.2",
+    "@battis/qui-cli.plugin": "^2.4.2",
+    "@battis/qui-cli.root": "^2.0.5",
+    "@battis/qui-cli.structured": "^0.1.5",
+    "handlebars": "^4.7.8",
+    "node-fetch": "^3.3.2",
+    "ora": "^8.2.0",
+    "p-queue": "^8.1.0",
+    "prettier": "3.5.3",
+    "prettier-plugin-jsdoc": "^1.3.3",
+    "prettier-plugin-organize-imports": "^4.2.0"
+  },
+  "devDependencies": {
+    "@battis/descriptive-types": "^0.2.3",
+    "@battis/typescript-tricks": "^0.7.4",
+    "@tsconfig/node20": "^20.1.6",
+    "commit-and-tag-version": "^12.5.2",
+    "del-cli": "^6.0.0",
+    "npm-run-all": "^4.1.5",
+    "typescript": "^5.8.3",
+    "@groton/swagger-spec-ts": "0.1.0"
+  },
+  "scripts": {
+    "clean": "del ./dist",
+    "build": "run-s build:*",
+    "build:clean": "run-s clean",
+    "build:compile": "tsc",
+    "release": "commit-and-tag-version"
+  }
+}