@amerilux/netsuite-api 0.1.0

package/dist-tooling/controllerReader.js

@@ -0,0 +1,267 @@
+import * as nodePath from 'node:path';
+import ts from 'typescript';
+import { toPosixPath } from './file-system.js';
+/** The return type a handler writes, exactly, to answer with a document instead of the envelope. */
+export const RAW_RESPONSE_TYPE_NAME = 'RawResponse';
+const controllerFileNamePattern = /^([a-z][A-Za-z0-9]*)Controller\.ts$/;
+const siblingControllerSpecifierPattern = /^\.\/[a-z][A-Za-z0-9]*Controller(?:\.js|\.ts)?$/;
+const entryPointByFunction = {
+    defineRestlet: { kind: 'restlet', exportName: 'post', header: 'Restlet' },
+    defineSuitelet: { kind: 'suitelet', exportName: 'onRequest', header: 'Suitelet' },
+};
+export function isControllerFileName(fileName) {
+    return controllerFileNamePattern.test(fileName);
+}
+export function toPascalCase(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function hasExportModifier(node) {
+    return ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+/** The JSDoc block directly above a node (no blank line between them), or undefined. */
+export function readLeadingJsDoc(node, sourceFile) {
+    const ranges = ts.getLeadingCommentRanges(sourceFile.text, node.getFullStart()) ?? [];
+    const jsDocRange = ranges.filter((range) => sourceFile.text.startsWith('/**', range.pos)).pop();
+    if (!jsDocRange)
+        return undefined;
+    const gap = sourceFile.text.slice(jsDocRange.end, node.getStart(sourceFile));
+    if (/\n[ \t]*\n/.test(gap))
+        return undefined;
+    return sourceFile.text.slice(jsDocRange.pos, jsDocRange.end);
+}
+/** The script type NetSuite reads from the leading JSDoc, or undefined. */
+function readScriptTypeHeader(source) {
+    const header = source.match(/^\s*(\/\*[\s\S]*?\*\/)/)?.[1] ?? '';
+    return header.match(/@NScriptType\s+(\w+)/)?.[1];
+}
+function readTypeImport(statement, filePath, options) {
+    const problems = [];
+    const clause = statement.importClause;
+    if (!clause || !ts.isStringLiteral(statement.moduleSpecifier))
+        return { problems };
+    const moduleSpecifier = statement.moduleSpecifier.text;
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) {
+        if (clause.isTypeOnly) {
+            problems.push({ filePath, message: `'import type * as ${bindings.name.text}' from '${moduleSpecifier}' cannot be carried to the client; import the types by name.` });
+        }
+        return { problems };
+    }
+    const names = [];
+    if (bindings && ts.isNamedImports(bindings)) {
+        for (const element of bindings.elements) {
+            if (clause.isTypeOnly || element.isTypeOnly)
+                names.push(element.propertyName ? `${element.propertyName.text} as ${element.name.text}` : element.name.text);
+        }
+    }
+    if (clause.name && clause.isTypeOnly) {
+        problems.push({ filePath, message: `'import type ${clause.name.text}' from '${moduleSpecifier}' cannot be carried to the client; import the types by name.` });
+    }
+    if (names.length === 0)
+        return { problems };
+    if (siblingControllerSpecifierPattern.test(moduleSpecifier))
+        return { problems };
+    const clientSpecifier = options.typeImports[moduleSpecifier];
+    if (clientSpecifier !== undefined)
+        return { typeImport: { moduleSpecifier: clientSpecifier, names }, problems };
+    const allowed = Object.keys(options.typeImports).map((specifier) => `'${specifier}'`).join(', ');
+    problems.push({ filePath, message: `type ${names.join(', ')} is imported from '${moduleSpecifier}'; a controller's wire shapes may only take types from ${allowed || 'the configured typeImports'} or from another controller.` });
+    return { problems };
+}
+function isTypeQueryAlias(statement) {
+    return ts.isTypeAliasDeclaration(statement) && ts.isTypeQueryNode(statement.type);
+}
+function readEndpoint(property, filePath, sourceFile) {
+    const problems = [];
+    const propertyName = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined;
+    if (propertyName === undefined) {
+        problems.push({ filePath, message: 'an endpoint must be named by a plain identifier.' });
+        return { problems };
+    }
+    let handler;
+    if (ts.isMethodDeclaration(property))
+        handler = property;
+    else if (ts.isPropertyAssignment(property) && (ts.isArrowFunction(property.initializer) || ts.isFunctionExpression(property.initializer)))
+        handler = property.initializer;
+    if (!handler) {
+        problems.push({ filePath, message: `endpoint '${propertyName}' must be an inline function with its parameter and return type annotated; a reference to a function elsewhere carries no types the generator can read.` });
+        return { problems };
+    }
+    if (handler.parameters.length > 1) {
+        problems.push({ filePath, message: `endpoint '${propertyName}' takes ${handler.parameters.length} parameters; an endpoint takes one request or none.` });
+        return { problems };
+    }
+    if (!handler.type) {
+        problems.push({ filePath, message: `endpoint '${propertyName}' has no return type annotation; the response shape is read from it.` });
+        return { problems };
+    }
+    const parameter = handler.parameters[0];
+    if (parameter && !parameter.type) {
+        problems.push({ filePath, message: `endpoint '${propertyName}' has no parameter type annotation; the request shape is read from it.` });
+        return { problems };
+    }
+    const responseType = handler.type.getText(sourceFile);
+    return {
+        endpoint: {
+            name: propertyName,
+            requestType: parameter?.type?.getText(sourceFile),
+            requestOptional: parameter?.questionToken !== undefined || parameter?.initializer !== undefined,
+            responseType,
+            raw: responseType === RAW_RESPONSE_TYPE_NAME,
+            jsDoc: readLeadingJsDoc(property, sourceFile),
+        },
+        problems,
+    };
+}
+function findCall(statement, calleeNames) {
+    for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name))
+            continue;
+        const initializer = declaration.initializer;
+        if (initializer && ts.isCallExpression(initializer) && ts.isIdentifier(initializer.expression) && calleeNames.includes(initializer.expression.text)) {
+            return { declarationName: declaration.name.text, call: initializer };
+        }
+    }
+    return undefined;
+}
+function readStringProperty(literal, propertyName) {
+    for (const property of literal.properties) {
+        if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === propertyName && ts.isStringLiteral(property.initializer))
+            return property.initializer.text;
+    }
+    return undefined;
+}
+function readBooleanProperty(literal, propertyName) {
+    for (const property of literal.properties) {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name) || property.name.text !== propertyName)
+            continue;
+        if (property.initializer.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (property.initializer.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+    }
+    return undefined;
+}
+function readScriptDeclaration(found, statement, controllerName, endpointsConstantName, source, filePath) {
+    const problems = [];
+    const calleeName = found.call.expression.text;
+    const entryPoint = entryPointByFunction[calleeName];
+    const callLabel = `${calleeName}({ name, scriptId, deployId }, ${endpointsConstantName})`;
+    if (!hasExportModifier(statement) || found.declarationName !== entryPoint.exportName) {
+        problems.push({ filePath, message: `the entry point must be 'export const ${entryPoint.exportName} = ${callLabel}'; NetSuite looks for that export on a ${entryPoint.header}.` });
+    }
+    const header = readScriptTypeHeader(source);
+    if (header !== entryPoint.header) {
+        problems.push({ filePath, message: `the leading JSDoc says '@NScriptType ${header ?? '(none)'}' but the entry point is ${calleeName}; both must say ${entryPoint.header}.` });
+    }
+    const [declaration, endpointsArgument] = found.call.arguments;
+    if (!declaration || !ts.isObjectLiteralExpression(declaration)) {
+        problems.push({ filePath, message: `${calleeName} takes the script declaration as an object literal written inline: ${callLabel}.` });
+        return { problems };
+    }
+    if (!endpointsArgument || !ts.isIdentifier(endpointsArgument) || endpointsArgument.text !== endpointsConstantName) {
+        problems.push({ filePath, message: `${calleeName} must be passed ${endpointsConstantName}: ${callLabel}.` });
+    }
+    const name = readStringProperty(declaration, 'name');
+    const scriptId = readStringProperty(declaration, 'scriptId');
+    const deployId = readStringProperty(declaration, 'deployId');
+    for (const [property, value] of [['name', name], ['scriptId', scriptId], ['deployId', deployId]]) {
+        if (value === undefined)
+            problems.push({ filePath, message: `the script declaration needs '${property}' as a string literal; the generator reads it from the source.` });
+    }
+    if (name !== undefined && name !== controllerName) {
+        problems.push({ filePath, message: `the script declaration says name: '${name}' but the file is ${controllerName}Controller.ts; the name is the file name without Controller.` });
+    }
+    const browser = readBooleanProperty(declaration, 'browser');
+    if (browser === undefined && declaration.properties.some((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'browser')) {
+        problems.push({ filePath, message: "'browser' must be the literal true or false." });
+    }
+    if (problems.length > 0 || scriptId === undefined || deployId === undefined)
+        return { problems };
+    return { script: { kind: entryPoint.kind, scriptId, deployId, browser: browser ?? true }, problems };
+}
+export function readControllerContract(filePath, source, options) {
+    const problems = [];
+    const fileName = nodePath.basename(toPosixPath(filePath));
+    const nameMatch = controllerFileNamePattern.exec(fileName);
+    if (!nameMatch) {
+        return { problems: [{ filePath, message: 'a controller file is named <name>Controller.ts, with <name> in camelCase.' }] };
+    }
+    const name = nameMatch[1];
+    const endpointsConstantName = `${name}Endpoints`;
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const typeImports = [];
+    const typeDeclarations = [];
+    const endpoints = [];
+    let endpointsFound = false;
+    let script;
+    let entryPointFound = false;
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const result = readTypeImport(statement, filePath, options);
+            problems.push(...result.problems);
+            if (result.typeImport)
+                typeImports.push(result.typeImport);
+        }
+        else if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) {
+            if (isTypeQueryAlias(statement)) {
+                const queried = statement.type;
+                if (ts.isIdentifier(queried.exprName) && queried.exprName.text === endpointsConstantName)
+                    continue;
+                problems.push({ filePath, message: `type '${statement.name.text}' is a typeof; a wire shape is written out as an interface or a type alias.` });
+                continue;
+            }
+            if (!hasExportModifier(statement)) {
+                problems.push({ filePath, message: `'${statement.name.text}' is not exported; every type in a controller is a wire shape, so export it (or move it below the controller).` });
+                continue;
+            }
+            const jsDoc = readLeadingJsDoc(statement, sourceFile);
+            typeDeclarations.push({ name: statement.name.text, text: `${jsDoc ? `${jsDoc}\n` : ''}${statement.getText(sourceFile)}` });
+        }
+        else if (ts.isVariableStatement(statement)) {
+            const endpointsCall = findCall(statement, ['defineEndpoints']);
+            if (endpointsCall) {
+                if (endpointsCall.declarationName !== endpointsConstantName) {
+                    problems.push({ filePath, message: `the endpoints are declared as 'export const ${endpointsConstantName} = defineEndpoints({ ... })', not '${endpointsCall.declarationName}'.` });
+                    continue;
+                }
+                endpointsFound = true;
+                const argument = endpointsCall.call.arguments[0];
+                if (!argument || !ts.isObjectLiteralExpression(argument)) {
+                    problems.push({ filePath, message: `${endpointsConstantName} must be defineEndpoints({ ... }) with the endpoints written inline.` });
+                    continue;
+                }
+                for (const property of argument.properties) {
+                    const result = readEndpoint(property, filePath, sourceFile);
+                    problems.push(...result.problems);
+                    if (result.endpoint)
+                        endpoints.push(result.endpoint);
+                }
+                continue;
+            }
+            const entryPointCall = findCall(statement, Object.keys(entryPointByFunction));
+            if (entryPointCall) {
+                if (entryPointFound) {
+                    problems.push({ filePath, message: 'a controller has one entry point; a second defineRestlet or defineSuitelet call is a second script.' });
+                    continue;
+                }
+                entryPointFound = true;
+                const result = readScriptDeclaration(entryPointCall, statement, name, endpointsConstantName, source, filePath);
+                problems.push(...result.problems);
+                script = result.script;
+            }
+        }
+    }
+    if (!endpointsFound) {
+        problems.push({ filePath, message: `must declare 'export const ${endpointsConstantName} = defineEndpoints({ ... })'.` });
+    }
+    if (!entryPointFound) {
+        problems.push({ filePath, message: `must end with 'export const post = defineRestlet({ name, scriptId, deployId }, ${endpointsConstantName})' or 'export const onRequest = defineSuitelet(...)'.` });
+    }
+    if (problems.length > 0 || !script)
+        return { problems };
+    return {
+        contract: { name, filePath, endpointsTypeName: `${toPascalCase(name)}Endpoints`, clientName: `${name}Api`, script, typeImports, typeDeclarations, endpoints },
+        problems,
+    };
+}

package/dist-tooling/emit.d.ts

@@ -0,0 +1,29 @@
+import type { ControllerContract } from './controllerReader.js';
+/**
+ * Writes the generated modules. The client module holds the app declarations, every controller's
+ * wire shapes and endpoint type, and a typed client for each controller the browser calls: one file,
+ * so a DTO that references another controller's type resolves in place and the client never imports
+ * from the api. The scripts module is the server-side map a repository passes to createSuiteletClient.
+ */
+export interface EmittedController {
+    contract: ControllerContract;
+    /** Where the file's header points a reader: the controller's path relative to the project. */
+    sourceLabel: string;
+}
+export interface EmitClientModuleOptions {
+    clientModule: string;
+    /** How the header names the sources: `api/src/controllers`. */
+    controllersLabel: string;
+}
+export interface EmitScriptsModuleOptions {
+    wireModule: string;
+    controllersLabel: string;
+}
+export interface EmitAppModuleOptions {
+    /** How the header names the app file: `netsuite.ts`. */
+    appLabel: string;
+}
+export declare function emitClientModule(controllers: EmittedController[], options: EmitClientModuleOptions): string;
+/** The app file as the client sees it: its exported declarations, verbatim. */
+export declare function emitAppModule(appDeclarations: string[], options: EmitAppModuleOptions): string;
+export declare function emitScriptsModule(controllers: EmittedController[], options: EmitScriptsModuleOptions): string;

package/dist-tooling/emit.js

@@ -0,0 +1,79 @@
+const INDENT = '    ';
+const EDIT_NOTICE = 'Do not edit: change the controller and run `npm run generate`.';
+function indentJsDoc(jsDoc) {
+    return jsDoc
+        .split('\n')
+        .map((line, index) => (index === 0 ? `${INDENT}${line.trim()}` : `${INDENT} ${line.trim()}`))
+        .join('\n');
+}
+function emitEndpointMember(endpoint) {
+    const parameter = endpoint.requestType === undefined ? '' : `request${endpoint.requestOptional ? '?' : ''}: ${endpoint.requestType}`;
+    const member = `${INDENT}${endpoint.name}: (${parameter}) => ${endpoint.responseType};`;
+    return endpoint.jsDoc ? `${indentJsDoc(endpoint.jsDoc)}\n${member}` : member;
+}
+function emitTypeImports(controllers) {
+    const namesByModule = new Map();
+    for (const { contract } of controllers) {
+        for (const typeImport of contract.typeImports) {
+            const names = namesByModule.get(typeImport.moduleSpecifier) ?? new Set();
+            typeImport.names.forEach((name) => names.add(name));
+            namesByModule.set(typeImport.moduleSpecifier, names);
+        }
+    }
+    return Array.from(namesByModule.keys())
+        .sort()
+        .map((moduleSpecifier) => `import type { ${Array.from(namesByModule.get(moduleSpecifier) ?? []).sort().join(', ')} } from '${moduleSpecifier}';`);
+}
+/** The script reference as a literal, as the client module and the scripts module write it. */
+function emitScriptRef(script) {
+    const browser = script.browser ? '' : ', browser: false';
+    return `{ kind: '${script.kind}', scriptId: '${script.scriptId}', deployId: '${script.deployId}'${browser} }`;
+}
+function emitController({ contract, sourceLabel }) {
+    const browser = contract.script.browser;
+    const sections = [`// ${contract.name} (${sourceLabel})${browser ? '' : ': called by server code only, so types only'}`];
+    for (const declaration of contract.typeDeclarations)
+        sections.push(declaration.text);
+    const members = contract.endpoints.map(emitEndpointMember);
+    // A type alias, not an interface: only an object type literal satisfies the Endpoints index signature.
+    sections.push(`export type ${contract.endpointsTypeName} = {\n${members.join('\n')}\n};`);
+    if (browser) {
+        const rawEndpoints = contract.endpoints.filter((endpoint) => endpoint.raw).map((endpoint) => `'${endpoint.name}'`);
+        const clientOptions = rawEndpoints.length > 0 ? `, { rawEndpoints: [${rawEndpoints.join(', ')}] }` : '';
+        sections.push(`/** One typed function per endpoint of the ${contract.name} controller: \`${contract.clientName}.${contract.endpoints[0]?.name ?? 'endpoint'}(...)\`. */\n` +
+            `export const ${contract.clientName} = createApiClient<${contract.endpointsTypeName}>(${emitScriptRef({ ...contract.script, browser: true })}${clientOptions});`);
+    }
+    return sections.join('\n\n');
+}
+function sortControllers(controllers) {
+    return [...controllers].sort((left, right) => left.contract.name.localeCompare(right.contract.name));
+}
+export function emitClientModule(controllers, options) {
+    const ordered = sortControllers(controllers);
+    const anyBrowserFacing = ordered.some((controller) => controller.contract.script.browser);
+    const header = [`// Generated by netsuite-api generate from ${options.controllersLabel}. ${EDIT_NOTICE}`, '/* eslint-disable */'];
+    const imports = [...(anyBrowserFacing ? [`import { createApiClient } from '${options.clientModule}';`] : []), ...emitTypeImports(ordered)];
+    const body = ordered.map(emitController);
+    return `${[header.join('\n'), imports.join('\n'), ...body].filter((section) => section !== '').join('\n\n')}\n`;
+}
+/** The app file as the client sees it: its exported declarations, verbatim. */
+export function emitAppModule(appDeclarations, options) {
+    const header = [`// Generated by netsuite-api generate from ${options.appLabel}. Do not edit: change ${options.appLabel} and run \`npm run generate\`.`, '/* eslint-disable */'];
+    return `${[header.join('\n'), ...appDeclarations].join('\n\n')}\n`;
+}
+export function emitScriptsModule(controllers, options) {
+    const ordered = sortControllers(controllers);
+    const entries = ordered.map(({ contract }) => `${INDENT}${contract.name}: ${emitScriptRef(contract.script)},`);
+    return [
+        `// Generated by netsuite-api generate from ${options.controllersLabel}. ${EDIT_NOTICE}`,
+        '/* eslint-disable */',
+        '',
+        `import type { ScriptRef } from '${options.wireModule}';`,
+        '',
+        '/** Every script the controllers declare, by controller name: what a repository passes to createSuiteletClient. */',
+        'export const scripts = {',
+        ...entries,
+        '} as const satisfies Record<string, ScriptRef>;',
+        '',
+    ].join('\n');
+}

package/dist-tooling/file-system.d.ts

@@ -0,0 +1,15 @@
+/** The file system surface the generator uses, so tests run fully in memory. */
+export interface FileSystemAdapter {
+    readTextFile(filePath: string): string;
+    writeTextFile(filePath: string, content: string): void;
+    fileExists(filePath: string): boolean;
+    ensureDirectory(directoryPath: string): void;
+    /** Lists the absolute paths of the files directly inside a directory. Returns [] when it does not exist. */
+    listFiles(directoryPath: string): string[];
+}
+export declare function toPosixPath(filePath: string): string;
+export declare function createNodeFileSystemAdapter(): FileSystemAdapter;
+export interface InMemoryFileSystemAdapter extends FileSystemAdapter {
+    readonly files: Map<string, string>;
+}
+export declare function createInMemoryFileSystemAdapter(initialFiles?: Record<string, string>): InMemoryFileSystemAdapter;

package/dist-tooling/file-system.js

@@ -0,0 +1,53 @@
+import * as nodeFileSystem from 'node:fs';
+import * as nodePath from 'node:path';
+export function toPosixPath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+export function createNodeFileSystemAdapter() {
+    return {
+        readTextFile: (filePath) => nodeFileSystem.readFileSync(filePath, 'utf8'),
+        writeTextFile: (filePath, content) => nodeFileSystem.writeFileSync(filePath, content, 'utf8'),
+        fileExists: (filePath) => nodeFileSystem.existsSync(filePath),
+        ensureDirectory: (directoryPath) => nodeFileSystem.mkdirSync(directoryPath, { recursive: true }),
+        listFiles: (directoryPath) => {
+            if (!nodeFileSystem.existsSync(directoryPath) || !nodeFileSystem.statSync(directoryPath).isDirectory())
+                return [];
+            return nodeFileSystem
+                .readdirSync(directoryPath, { withFileTypes: true })
+                .filter((entry) => entry.isFile())
+                .map((entry) => nodePath.join(directoryPath, entry.name))
+                .sort();
+        },
+    };
+}
+function normalizeKey(filePath) {
+    return toPosixPath(nodePath.resolve(filePath));
+}
+export function createInMemoryFileSystemAdapter(initialFiles = {}) {
+    const files = new Map();
+    const directories = new Set();
+    for (const [filePath, content] of Object.entries(initialFiles))
+        files.set(normalizeKey(filePath), content);
+    return {
+        files,
+        readTextFile: (filePath) => {
+            const content = files.get(normalizeKey(filePath));
+            if (content === undefined)
+                throw new Error(`File not found: ${filePath}`);
+            return content;
+        },
+        writeTextFile: (filePath, content) => {
+            files.set(normalizeKey(filePath), content);
+        },
+        fileExists: (filePath) => files.has(normalizeKey(filePath)) || directories.has(normalizeKey(filePath)),
+        ensureDirectory: (directoryPath) => {
+            directories.add(normalizeKey(directoryPath));
+        },
+        listFiles: (directoryPath) => {
+            const prefix = `${normalizeKey(directoryPath)}/`;
+            return Array.from(files.keys())
+                .filter((filePath) => filePath.startsWith(prefix) && !filePath.slice(prefix.length).includes('/'))
+                .sort();
+        },
+    };
+}

package/dist-tooling/generate.d.ts

@@ -0,0 +1,36 @@
+import type { ResolvedClientGeneratorConfig } from './config.js';
+import type { ControllerProblem } from './controllerReader.js';
+import type { FileSystemAdapter } from './file-system.js';
+export interface GenerateClientOptions {
+    config: ResolvedClientGeneratorConfig;
+    fileSystem: FileSystemAdapter;
+}
+export interface PlannedController {
+    name: string;
+    filePath: string;
+    kind: 'restlet' | 'suitelet';
+    browser: boolean;
+    endpointCount: number;
+}
+export interface PlannedFile {
+    /** Absolute path. */
+    path: string;
+    content: string;
+}
+export interface ClientGenerationPlan {
+    /** The modules to write and the files to copy; empty when there are problems. */
+    files: PlannedFile[];
+    controllers: PlannedController[];
+    problems: ControllerProblem[];
+}
+export interface ClientGenerationResult extends ClientGenerationPlan {
+    writtenFiles: string[];
+    unchangedFiles: string[];
+}
+export interface ClientGenerationCheck extends ClientGenerationPlan {
+    missingFiles: string[];
+    staleFiles: string[];
+}
+export declare function planClientGeneration({ config, fileSystem }: GenerateClientOptions): ClientGenerationPlan;
+export declare function runClientGeneration(options: GenerateClientOptions): ClientGenerationResult;
+export declare function checkClientGeneration(options: GenerateClientOptions): ClientGenerationCheck;

package/dist-tooling/generate.js

@@ -0,0 +1,128 @@
+import * as nodePath from 'node:path';
+import { readAppDeclarations } from './appReader.js';
+import { isControllerFileName, readControllerContract } from './controllerReader.js';
+import { emitAppModule, emitClientModule, emitScriptsModule } from './emit.js';
+import { toPosixPath } from './file-system.js';
+function relativeLabel(rootDirectory, filePath) {
+    return toPosixPath(nodePath.relative(rootDirectory, filePath));
+}
+function findDuplicateNames(controllers) {
+    const owners = new Map();
+    const problems = [];
+    const claim = (name, filePath, what) => {
+        const owner = owners.get(name);
+        if (owner !== undefined && owner !== filePath) {
+            problems.push({ filePath, message: `${what} '${name}' is also declared by ${owner}; the generated module holds every controller, so names are unique across them.` });
+        }
+        else {
+            owners.set(name, filePath);
+        }
+    };
+    for (const { contract } of controllers) {
+        for (const declaration of contract.typeDeclarations)
+            claim(declaration.name, contract.filePath, 'type');
+        claim(contract.endpointsTypeName, contract.filePath, 'type');
+        claim(contract.clientName, contract.filePath, 'client');
+    }
+    return problems;
+}
+function findDuplicateScriptIds(controllers) {
+    const problems = [];
+    for (const property of ['scriptId', 'deployId']) {
+        const owners = new Map();
+        for (const { contract } of controllers) {
+            const id = contract.script[property];
+            const owner = owners.get(id);
+            if (owner !== undefined)
+                problems.push({ filePath: contract.filePath, message: `${property} '${id}' is also declared by ${owner}; every controller is its own script.` });
+            else
+                owners.set(id, contract.filePath);
+        }
+    }
+    return problems;
+}
+export function planClientGeneration({ config, fileSystem }) {
+    const resolve = (relativePath) => nodePath.resolve(config.rootDirectory, relativePath);
+    const label = (absolutePath) => relativeLabel(config.rootDirectory, absolutePath);
+    const controllersDirectory = resolve(config.controllers);
+    const appFile = resolve(config.appFile);
+    const problems = [];
+    const controllerFiles = fileSystem.listFiles(controllersDirectory).filter((filePath) => isControllerFileName(nodePath.basename(filePath)));
+    if (controllerFiles.length === 0) {
+        problems.push({ filePath: label(controllersDirectory), message: 'holds no <name>Controller.ts file.' });
+    }
+    const emitted = [];
+    for (const filePath of controllerFiles) {
+        const result = readControllerContract(label(filePath), fileSystem.readTextFile(filePath), { typeImports: config.typeImports });
+        problems.push(...result.problems);
+        if (result.contract)
+            emitted.push({ contract: result.contract, sourceLabel: label(filePath) });
+    }
+    problems.push(...findDuplicateNames(emitted), ...findDuplicateScriptIds(emitted));
+    let appDeclarations = [];
+    if (fileSystem.fileExists(appFile)) {
+        const app = readAppDeclarations(label(appFile), fileSystem.readTextFile(appFile));
+        problems.push(...app.problems);
+        appDeclarations = app.declarations;
+    }
+    else {
+        problems.push({ filePath: label(appFile), message: 'the app file does not exist.' });
+    }
+    const copies = [];
+    for (const [source, destination] of Object.entries(config.copyFiles)) {
+        const sourcePath = resolve(source);
+        if (!fileSystem.fileExists(sourcePath)) {
+            problems.push({ filePath: label(sourcePath), message: 'the file to copy into the client does not exist; run the model generator first.' });
+            continue;
+        }
+        copies.push({ path: resolve(destination), content: fileSystem.readTextFile(sourcePath) });
+    }
+    const controllers = emitted.map(({ contract }) => ({
+        name: contract.name,
+        filePath: contract.filePath,
+        kind: contract.script.kind,
+        browser: contract.script.browser,
+        endpointCount: contract.endpoints.length,
+    }));
+    if (problems.length > 0)
+        return { files: [], controllers, problems };
+    const controllersLabel = label(controllersDirectory);
+    const files = [
+        { path: resolve(config.outFile), content: emitClientModule(emitted, { clientModule: config.clientModule, controllersLabel }) },
+        { path: resolve(config.appOutFile), content: emitAppModule(appDeclarations, { appLabel: label(appFile) }) },
+        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel }) },
+        ...copies,
+    ];
+    return { files, controllers, problems };
+}
+export function runClientGeneration(options) {
+    const plan = planClientGeneration(options);
+    const writtenFiles = [];
+    const unchangedFiles = [];
+    if (plan.problems.length > 0)
+        return { ...plan, writtenFiles, unchangedFiles };
+    const { fileSystem } = options;
+    for (const file of plan.files) {
+        if (fileSystem.fileExists(file.path) && fileSystem.readTextFile(file.path) === file.content) {
+            unchangedFiles.push(file.path);
+            continue;
+        }
+        fileSystem.ensureDirectory(nodePath.dirname(file.path));
+        fileSystem.writeTextFile(file.path, file.content);
+        writtenFiles.push(file.path);
+    }
+    return { ...plan, writtenFiles, unchangedFiles };
+}
+export function checkClientGeneration(options) {
+    const plan = planClientGeneration(options);
+    const { fileSystem } = options;
+    const missingFiles = [];
+    const staleFiles = [];
+    for (const file of plan.files) {
+        if (!fileSystem.fileExists(file.path))
+            missingFiles.push(file.path);
+        else if (fileSystem.readTextFile(file.path) !== file.content)
+            staleFiles.push(file.path);
+    }
+    return { ...plan, missingFiles, staleFiles };
+}

package/dist-tooling/index.d.ts

@@ -0,0 +1,15 @@
+/** The generator as a library: what the `netsuite-api` command runs, for a build tool or a test to call directly. */
+export { DEFAULT_CONFIG_FILE_NAME, ClientGeneratorConfigError, defaultClientGeneratorConfig, loadClientGeneratorConfig } from './config.js';
+export type { ClientGeneratorConfig, ResolvedClientGeneratorConfig } from './config.js';
+export { RAW_RESPONSE_TYPE_NAME, isControllerFileName, readControllerContract, readLeadingJsDoc, toPascalCase } from './controllerReader.js';
+export type { CarriedTypeImport, ControllerContract, ControllerKind, ControllerProblem, ControllerReadResult, DeclaredScript, EndpointSignature, ReadControllerOptions, TypeDeclaration } from './controllerReader.js';
+export { readAppDeclarations } from './appReader.js';
+export type { AppDeclarations } from './appReader.js';
+export { emitAppModule, emitClientModule, emitScriptsModule } from './emit.js';
+export type { EmitAppModuleOptions, EmitClientModuleOptions, EmitScriptsModuleOptions, EmittedController } from './emit.js';
+export { checkClientGeneration, planClientGeneration, runClientGeneration } from './generate.js';
+export type { ClientGenerationCheck, ClientGenerationPlan, ClientGenerationResult, GenerateClientOptions, PlannedController, PlannedFile } from './generate.js';
+export { createInMemoryFileSystemAdapter, createNodeFileSystemAdapter, toPosixPath } from './file-system.js';
+export type { FileSystemAdapter, InMemoryFileSystemAdapter } from './file-system.js';
+export { CLI_USAGE, EXIT_PROBLEMS, EXIT_SUCCESS, EXIT_USAGE, runCli } from './cli/main.js';
+export type { CliEnvironment } from './cli/main.js';

package/dist-tooling/index.js

@@ -0,0 +1,8 @@
+/** The generator as a library: what the `netsuite-api` command runs, for a build tool or a test to call directly. */
+export { DEFAULT_CONFIG_FILE_NAME, ClientGeneratorConfigError, defaultClientGeneratorConfig, loadClientGeneratorConfig } from './config.js';
+export { RAW_RESPONSE_TYPE_NAME, isControllerFileName, readControllerContract, readLeadingJsDoc, toPascalCase } from './controllerReader.js';
+export { readAppDeclarations } from './appReader.js';
+export { emitAppModule, emitClientModule, emitScriptsModule } from './emit.js';
+export { checkClientGeneration, planClientGeneration, runClientGeneration } from './generate.js';
+export { createInMemoryFileSystemAdapter, createNodeFileSystemAdapter, toPosixPath } from './file-system.js';
+export { CLI_USAGE, EXIT_PROBLEMS, EXIT_SUCCESS, EXIT_USAGE, runCli } from './cli/main.js';

package/dist-tooling/scriptsReader.d.ts

@@ -0,0 +1,17 @@
+import type { ControllerProblem } from './controllerReader.js';
+/**
+ * Reads the `scripts` map of a project from its source: which scripts exist, and which the browser
+ * calls. The file cannot be executed here (a template renders placeholders into it), so this is a
+ * parse of `export const scripts = { name: { kind, scriptId, deployId, browser? }, ... }`.
+ */
+export interface ScriptRegistryEntry {
+    name: string;
+    kind?: string;
+    /** False only when the entry says `browser: false`. */
+    browser: boolean;
+}
+export interface ScriptRegistryReadResult {
+    entries: Map<string, ScriptRegistryEntry>;
+    problems: ControllerProblem[];
+}
+export declare function readScriptRegistry(filePath: string, source: string): ScriptRegistryReadResult;