@amerilux/netsuite-api 0.2.1 → 0.5.0

package/dist-tooling/generate.js

@@ -1,23 +1,97 @@
 import * as nodePath from 'node:path';
+import { resolveInlineTypesFile, resolveJobRunFieldIds } from './config.js';
 import { isControllerFileName, readControllerContract } from './controllerReader.js';
-import { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule, sortControllers } from './emit.js';
+import { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName, sortControllers, sortJobs, } from './emit.js';
+import { isJobFileName, readJobContract } from './jobReader.js';
 import { toPosixPath } from './file-system.js';
 import { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
+import { readReferencedNames } from './wireTypes.js';
 const generatedFileNamePattern = /\.gen\.ts$/;
 function relativeLabel(rootDirectory, filePath) {
     return toPosixPath(nodePath.relative(rootDirectory, filePath));
 }
-function findDuplicateScriptIds(controllers) {
+function findDuplicateScriptIds(controllers, jobs) {
     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);
+    const scriptOwners = new Map();
+    const deployOwners = new Map();
+    const claim = (owners, id, filePath, label) => {
+        const owner = owners.get(id);
+        if (owner !== undefined)
+            problems.push({ filePath, message: `${label} '${id}' is also declared by ${owner}; every controller and every job is its own script.` });
+        else
+            owners.set(id, filePath);
+    };
+    for (const { contract } of controllers) {
+        claim(scriptOwners, contract.script.scriptId, contract.filePath, 'scriptId');
+        claim(deployOwners, contract.script.deployId, contract.filePath, 'deployId');
+    }
+    for (const { contract } of jobs) {
+        claim(scriptOwners, contract.script.scriptId, contract.filePath, 'scriptId');
+        for (const deployment of contract.script.deployments)
+            claim(deployOwners, deployment, contract.filePath, 'deployment');
+    }
+    return problems;
+}
+/** Every type declaration a shape can be built from: the file's own, then the ones copied into it. */
+function collectDeclarations(own, inlinedTypes) {
+    const declarations = new Map();
+    for (const declaration of own)
+        declarations.set(declaration.name, declaration.text);
+    for (const section of inlinedTypes) {
+        for (const declaration of section.declarations)
+            if (!declarations.has(declaration.name))
+                declarations.set(declaration.name, declaration.text);
+    }
+    return declarations;
+}
+/**
+ * A Date reached from a run's input: it is stored as JSON on the run record, so the stage would
+ * receive an ISO string where its annotation promises a Date. The result is not checked, because
+ * nothing reads it back as a Date; the browser sees whatever summarize wrote.
+ */
+function findDatesInJobInput(contract, inlinedTypes, jobLabel) {
+    if (contract.inputType === undefined)
+        return [];
+    const declarations = collectDeclarations(contract.typeDeclarations, inlinedTypes);
+    const visited = new Set();
+    const pending = readReferencedNames(contract.inputType, 'type').map((name) => ({ name, via: contract.inputType }));
+    while (pending.length > 0) {
+        const { name, via } = pending.shift();
+        if (name === 'Date') {
+            return [{ filePath: jobLabel, message: `getInputData takes a Date in its input (through ${via}); a run carries its input as JSON, so take a string and parse it in the stage.` }];
+        }
+        const text = declarations.get(name);
+        if (text === undefined || visited.has(name))
+            continue;
+        visited.add(name);
+        pending.push(...readReferencedNames(text, 'declaration').map((reference) => ({ name: reference, via: name })));
+    }
+    return [];
+}
+/**
+ * A Date reached from a request shape, through the controller's own declarations and the copied
+ * ones: the handler would receive an ISO string where its annotation promises a Date. (A shape taken
+ * from a sibling controller is checked where it is declared, as that controller's own request.)
+ */
+function findDatesInRequestShapes(contract, inlinedTypes, controllerLabel) {
+    const declarations = collectDeclarations(contract.typeDeclarations, inlinedTypes);
+    const problems = [];
+    for (const endpoint of contract.endpoints) {
+        if (endpoint.requestType === undefined)
+            continue;
+        const visited = new Set();
+        const pending = readReferencedNames(endpoint.requestType, 'type').map((name) => ({ name, via: endpoint.requestType }));
+        while (pending.length > 0) {
+            const { name, via } = pending.shift();
+            if (name === 'Date') {
+                problems.push({ filePath: controllerLabel, message: `endpoint '${endpoint.name}' takes a Date in its request (through ${via}); JSON carries dates as ISO 8601 strings, so take a string and parse it in the handler.` });
+                break;
+            }
+            const text = declarations.get(name);
+            if (text === undefined || visited.has(name))
+                continue;
+            visited.add(name);
+            pending.push(...readReferencedNames(text, 'declaration').map((reference) => ({ name: reference, via: name })));
         }
     }
     return problems;
@@ -41,15 +115,23 @@ export function planClientGeneration({ config, fileSystem }) {
     }
     const controllerNames = new Set(controllerFiles.map((filePath) => nodePath.basename(filePath).replace(/Controller\.ts$/, '')));
     const inlinableFiles = new Map();
+    /** The inlinable file a specifier names, read once; a file that does not exist is reported once and answered as 'missing'. */
     const readInlinable = (specifier) => {
-        if (inlinableFiles.has(specifier))
-            return inlinableFiles.get(specifier);
-        const filePath = resolve(config.inlineTypes[specifier]);
+        const known = inlinableFiles.get(specifier);
+        if (known !== undefined)
+            return known;
+        const relativePath = resolveInlineTypesFile(config.inlineTypes, specifier);
+        if (relativePath === undefined)
+            return undefined;
+        const filePath = resolve(relativePath);
         let file;
         if (fileSystem.fileExists(filePath))
             file = readInlinableTypesFile(label(filePath), fileSystem.readTextFile(filePath));
-        else
-            problems.push({ filePath: label(filePath), message: 'the file to copy types from does not exist; run the model generator first.' });
+        else {
+            file = 'missing';
+            const hint = config.inlineTypes[specifier] !== undefined ? 'run the model generator first.' : `'${specifier}' names it.`;
+            problems.push({ filePath: label(filePath), message: `the file to copy types from does not exist; ${hint}` });
+        }
         inlinableFiles.set(specifier, file);
         return file;
     };
@@ -72,19 +154,63 @@ export function planClientGeneration({ config, fileSystem }) {
         const inlinedTypes = [];
         for (const typeImport of contract.inlinedTypeImports) {
             const file = readInlinable(typeImport.specifier);
-            if (!file)
+            if (!file || file === 'missing')
                 continue;
-            const selected = selectInlinedTypes(file, typeImport.names, controllerLabel);
+            const selected = selectInlinedTypes(file, typeImport.names, controllerLabel, readInlinable);
             problems.push(...selected.problems);
-            const section = inlinedTypes.find((existing) => existing.sourceLabel === file.filePath);
-            if (section)
-                section.declarations.push(...selected.declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
-            else
-                inlinedTypes.push({ sourceLabel: file.filePath, declarations: selected.declarations });
+            for (const selectedSection of selected.sections) {
+                const section = inlinedTypes.find((existing) => existing.sourceLabel === selectedSection.filePath);
+                if (section)
+                    section.declarations.push(...selectedSection.declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
+                else
+                    inlinedTypes.push({ sourceLabel: selectedSection.filePath, declarations: selectedSection.declarations });
+            }
         }
+        problems.push(...findDatesInRequestShapes(contract, inlinedTypes, controllerLabel));
         emitted.push({ contract, sourceLabel: controllerLabel, inlinedTypes });
     }
-    problems.push(...findDuplicateScriptIds(emitted));
+    // Jobs: the same reading, with a run instead of a request and a record instead of a reply.
+    const jobsDirectory = resolve(config.jobs);
+    const emittedJobs = [];
+    for (const filePath of fileSystem.listFiles(jobsDirectory)) {
+        const jobLabel = label(filePath);
+        if (!isJobFileName(nodePath.basename(filePath))) {
+            problems.push({ filePath: jobLabel, message: 'a job file is named <name>.ts, with <name> in camelCase; nothing else lives in the jobs folder.' });
+            continue;
+        }
+        const result = readJobContract(jobLabel, fileSystem.readTextFile(filePath), { typeImports: config.typeImports, inlineTypes: config.inlineTypes });
+        problems.push(...result.problems);
+        const contract = result.contract;
+        if (!contract)
+            continue;
+        if (controllerNames.has(contract.name) && jobModuleFileName(contract.name) === controllerModuleFileName(contract.name)) {
+            problems.push({ filePath: jobLabel, message: `a controller is named '${contract.name}' too; their generated modules would be the same file.` });
+        }
+        const inlinedTypes = [];
+        for (const typeImport of contract.inlinedTypeImports) {
+            const file = readInlinable(typeImport.specifier);
+            if (!file || file === 'missing')
+                continue;
+            const selected = selectInlinedTypes(file, typeImport.names, jobLabel, readInlinable);
+            problems.push(...selected.problems);
+            for (const selectedSection of selected.sections) {
+                const section = inlinedTypes.find((existing) => existing.sourceLabel === selectedSection.filePath);
+                if (section)
+                    section.declarations.push(...selectedSection.declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
+                else
+                    inlinedTypes.push({ sourceLabel: selectedSection.filePath, declarations: selectedSection.declarations });
+            }
+        }
+        problems.push(...findDatesInJobInput(contract, inlinedTypes, jobLabel));
+        emittedJobs.push({ contract, sourceLabel: jobLabel, inlinedTypes });
+    }
+    if (emittedJobs.length > 0 && config.jobRuns === undefined) {
+        problems.push({
+            filePath: label(jobsDirectory),
+            message: 'the project has jobs but no run record: add the `jobRuns` block to netsuite-api.config.json (`npm run add:jobs` writes it, with the record itself).',
+        });
+    }
+    problems.push(...findDuplicateScriptIds(emitted, emittedJobs));
     const controllers = emitted.map(({ contract }) => ({
         name: contract.name,
         filePath: contract.filePath,
@@ -92,19 +218,31 @@ export function planClientGeneration({ config, fileSystem }) {
         browser: contract.script.browser,
         endpointCount: contract.endpoints.length,
     }));
+    const jobs = emittedJobs.map(({ contract }) => ({
+        name: contract.name,
+        filePath: contract.filePath,
+        stages: contract.stages,
+        deploymentCount: contract.script.deployments.length,
+    }));
     if (problems.length > 0)
-        return { files: [], leftoverFiles: [], controllers, problems };
+        return { files: [], leftoverFiles: [], controllers, jobs, problems };
     const controllersLabel = label(controllersDirectory);
+    const jobsLabel = label(jobsDirectory);
+    const jobRuns = config.jobRuns
+        ? { recordType: config.jobRuns.recordType, fields: resolveJobRunFieldIds(config.jobRuns), extraFields: config.jobRuns.extraFields ?? {} }
+        : undefined;
     const files = [
         ...sortControllers(emitted).map((controller) => ({
             path: nodePath.join(outDirectory, controllerModuleFileName(controller.contract.name)),
             content: emitControllerModule(controller, { clientModule: config.clientModule }),
         })),
-        { path: nodePath.join(outDirectory, CLIENT_INDEX_FILE_NAME), content: emitClientIndexModule(emitted, { controllersLabel }) },
-        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel }) },
+        ...sortJobs(emittedJobs).map((job) => ({ path: nodePath.join(outDirectory, jobModuleFileName(job.contract.name)), content: emitJobModule(job) })),
+        ...(emittedJobs.length > 0 ? [{ path: nodePath.join(outDirectory, JOBS_INDEX_FILE_NAME), content: emitJobsIndexModule(emittedJobs, { jobsLabel }) }] : []),
+        { path: nodePath.join(outDirectory, CLIENT_INDEX_FILE_NAME), content: emitClientIndexModule(emitted, { controllersLabel, hasJobs: emittedJobs.length > 0 }) },
+        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel, jobs: emittedJobs, jobsLabel, jobRuns }) },
     ];
     const leftoverFiles = findLeftoverFiles(fileSystem, outDirectory, files.map((file) => file.path));
-    return { files, leftoverFiles, controllers, problems };
+    return { files, leftoverFiles, controllers, jobs, problems };
 }
 export function runClientGeneration(options) {
     const plan = planClientGeneration(options);

package/dist-tooling/index.d.ts

@@ -1,14 +1,17 @@
 /** 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 { JOB_RUN_FIELD_SUFFIXES, netsuiteValueTypeNames, resolveJobRunFieldIds } from './config.js';
+export type { ClientGeneratorConfig, JobRunFieldName, JobRunsSettings, NetsuiteValueTypeName, ResolvedClientGeneratorConfig } from './config.js';
 export { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME, RAW_RESPONSE_TYPE_NAME, isControllerFileName, readControllerContract, readLeadingJsDoc } from './controllerReader.js';
 export type { CarriedTypeImport, ControllerContract, ControllerKind, ControllerProblem, ControllerReadResult, ControllerTypeImport, DeclaredScript, EndpointSignature, InlinedTypeImport, ReadControllerOptions, TypeDeclaration, TypeImportName } from './controllerReader.js';
+export { GENERATED_JOB_RESULT_TYPE_NAME, JOB_SCRIPT_TYPE_HEADER, JOB_STAGE_NAMES, isJobFileName, readJobContract } from './jobReader.js';
+export type { DeclaredJob, JobContract, JobParameterContract, JobReadResult, JobStageName } from './jobReader.js';
 export { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
 export type { InlinableTypeDeclaration, InlinableTypesFile, SelectedInlinedTypes } from './typesFileReader.js';
-export { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule } from './emit.js';
-export type { EmitClientIndexModuleOptions, EmitControllerModuleOptions, EmitScriptsModuleOptions, EmittedController, InlinedTypeSection } from './emit.js';
+export { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName } from './emit.js';
+export type { EmitClientIndexModuleOptions, EmitControllerModuleOptions, EmitScriptsModuleOptions, EmittedController, EmittedJob, EmittedJobRuns, InlinedTypeSection } from './emit.js';
 export { checkClientGeneration, planClientGeneration, runClientGeneration } from './generate.js';
-export type { ClientGenerationCheck, ClientGenerationPlan, ClientGenerationResult, GenerateClientOptions, PlannedController, PlannedFile } from './generate.js';
+export type { ClientGenerationCheck, ClientGenerationPlan, ClientGenerationResult, GenerateClientOptions, PlannedController, PlannedFile, PlannedJob } 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';

package/dist-tooling/index.js

@@ -1,8 +1,10 @@
 /** 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 { JOB_RUN_FIELD_SUFFIXES, netsuiteValueTypeNames, resolveJobRunFieldIds } from './config.js';
 export { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME, RAW_RESPONSE_TYPE_NAME, isControllerFileName, readControllerContract, readLeadingJsDoc } from './controllerReader.js';
+export { GENERATED_JOB_RESULT_TYPE_NAME, JOB_SCRIPT_TYPE_HEADER, JOB_STAGE_NAMES, isJobFileName, readJobContract } from './jobReader.js';
 export { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
-export { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule } from './emit.js';
+export { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName } 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/jobReader.d.ts

@@ -0,0 +1,53 @@
+import type { CarriedTypeImport, ControllerProblem, InlinedTypeImport, ReadControllerOptions, TypeDeclaration } from './controllerReader.js';
+/**
+ * Reads what a job run carries, from its source alone: the script it declares in its defineJob call,
+ * the stages it has, and the types on either end of a run. A run's input is the first parameter of
+ * getInputData and its result is what summarize returns, so those two annotations are the contract,
+ * the way a handler's parameter and return type are a controller's. A parse, not a type check: the
+ * ids are string literals and the shapes are written out.
+ */
+/** The stage names a job may declare, in the order NetSuite calls them. */
+export declare const JOB_STAGE_NAMES: readonly ["getInputData", "map", "reduce", "summarize"];
+export type JobStageName = (typeof JOB_STAGE_NAMES)[number];
+/** The script type a job's leading JSDoc must declare. */
+export declare const JOB_SCRIPT_TYPE_HEADER = "MapReduceScript";
+/** The type the generated job module gives the run's input, and the one it gives the result. */
+export declare const GENERATED_JOB_RESULT_TYPE_NAME = "Result";
+declare const netsuiteValueTypes: readonly ["text", "integer", "decimal", "checkbox", "date", "select"];
+export interface JobParameterContract {
+    /** The name the stages read it by. */
+    name: string;
+    id: string;
+    type: (typeof netsuiteValueTypes)[number];
+}
+/** The script a job declares, as read off its defineJob call. */
+export interface DeclaredJob {
+    scriptId: string;
+    deployments: string[];
+    runParameter: string;
+    parameters: JobParameterContract[];
+}
+export interface JobContract {
+    /** The job's name: `closeStaleOrders` for closeStaleOrders.ts, matching `name` in its declaration. */
+    name: string;
+    filePath: string;
+    script: DeclaredJob;
+    carriedTypeImports: CarriedTypeImport[];
+    inlinedTypeImports: InlinedTypeImport[];
+    typeDeclarations: TypeDeclaration[];
+    /** The type of getInputData's first parameter, or undefined when a run takes no input. */
+    inputType?: string;
+    /** What summarize returns, or undefined when the job has no summarize stage of its own. */
+    resultType?: string;
+    /** The stages the job declares. */
+    stages: JobStageName[];
+    /** The stages the file exports as NetSuite entry points. */
+    exportedStages: string[];
+}
+export interface JobReadResult {
+    contract?: JobContract;
+    problems: ControllerProblem[];
+}
+export declare function isJobFileName(fileName: string): boolean;
+export declare function readJobContract(filePath: string, source: string, options: ReadControllerOptions): JobReadResult;
+export {};

package/dist-tooling/jobReader.js

@@ -0,0 +1,260 @@
+import * as nodePath from 'node:path';
+import ts from 'typescript';
+import { hasExportModifier, readLeadingJsDoc, readScriptTypeHeader, readStringProperty, readTypeImport } from './controllerReader.js';
+import { toPosixPath } from './file-system.js';
+/**
+ * Reads what a job run carries, from its source alone: the script it declares in its defineJob call,
+ * the stages it has, and the types on either end of a run. A run's input is the first parameter of
+ * getInputData and its result is what summarize returns, so those two annotations are the contract,
+ * the way a handler's parameter and return type are a controller's. A parse, not a type check: the
+ * ids are string literals and the shapes are written out.
+ */
+/** The stage names a job may declare, in the order NetSuite calls them. */
+export const JOB_STAGE_NAMES = ['getInputData', 'map', 'reduce', 'summarize'];
+/** The script type a job's leading JSDoc must declare. */
+export const JOB_SCRIPT_TYPE_HEADER = 'MapReduceScript';
+/** The type the generated job module gives the run's input, and the one it gives the result. */
+export const GENERATED_JOB_RESULT_TYPE_NAME = 'Result';
+const jobFileNamePattern = /^([a-z][A-Za-z0-9]*)\.ts$/;
+const netsuiteValueTypes = ['text', 'integer', 'decimal', 'checkbox', 'date', 'select'];
+export function isJobFileName(fileName) {
+    return jobFileNamePattern.test(fileName) && !fileName.endsWith('.d.ts');
+}
+/** `export const { getInputData, map, summarize } = defineJob(...)`: the call, and the names it exports. */
+function findDefineJobCall(statement) {
+    for (const declaration of statement.declarationList.declarations) {
+        const initializer = declaration.initializer;
+        if (!initializer || !ts.isCallExpression(initializer) || !ts.isIdentifier(initializer.expression) || initializer.expression.text !== 'defineJob')
+            continue;
+        if (!ts.isObjectBindingPattern(declaration.name))
+            return { call: initializer, exportedStages: [], destructured: false };
+        const exportedStages = declaration.name.elements
+            .map((element) => (ts.isIdentifier(element.name) ? element.name.text : undefined))
+            .filter((exported) => exported !== undefined);
+        return { call: initializer, exportedStages, destructured: true };
+    }
+    return undefined;
+}
+function readStringArrayProperty(literal, propertyName) {
+    for (const property of literal.properties) {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name) || property.name.text !== propertyName)
+            continue;
+        if (!ts.isArrayLiteralExpression(property.initializer))
+            return undefined;
+        const values = property.initializer.elements.map((element) => (ts.isStringLiteral(element) ? element.text : undefined));
+        return values.every((value) => value !== undefined) ? values : undefined;
+    }
+    return undefined;
+}
+function hasProperty(literal, propertyName) {
+    return literal.properties.some((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === propertyName);
+}
+function readObjectProperty(literal, propertyName) {
+    for (const property of literal.properties) {
+        if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === propertyName && ts.isObjectLiteralExpression(property.initializer)) {
+            return property.initializer;
+        }
+    }
+    return undefined;
+}
+function readParameters(declaration, filePath) {
+    const problems = [];
+    const parameters = [];
+    const literal = readObjectProperty(declaration, 'parameters');
+    if (!literal) {
+        if (hasProperty(declaration, 'parameters'))
+            problems.push({ filePath, message: "'parameters' must be an object literal of { id, type } written inline; the generator reads the ids from it." });
+        return { parameters, problems };
+    }
+    for (const property of literal.properties) {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) {
+            problems.push({ filePath, message: 'every script parameter is named by a plain identifier and declared as { id, type }.' });
+            continue;
+        }
+        const name = property.name.text;
+        if (!ts.isObjectLiteralExpression(property.initializer)) {
+            problems.push({ filePath, message: `parameter '${name}' must be written as { id: 'custscript_...', type: '...' }.` });
+            continue;
+        }
+        const id = readStringProperty(property.initializer, 'id');
+        const type = readStringProperty(property.initializer, 'type');
+        if (id === undefined)
+            problems.push({ filePath, message: `parameter '${name}' needs 'id' as a string literal: the script parameter's id in NetSuite.` });
+        if (type === undefined || !netsuiteValueTypes.includes(type)) {
+            problems.push({ filePath, message: `parameter '${name}' needs 'type' as one of ${netsuiteValueTypes.map((value) => `'${value}'`).join(', ')}.` });
+            continue;
+        }
+        if (id !== undefined)
+            parameters.push({ name, id, type: type });
+    }
+    return { parameters, problems };
+}
+function readJobDeclaration(declaration, jobName, filePath) {
+    const problems = [];
+    const name = readStringProperty(declaration, 'name');
+    const scriptId = readStringProperty(declaration, 'scriptId');
+    const runParameter = readStringProperty(declaration, 'runParameter');
+    const deployments = readStringArrayProperty(declaration, 'deployments');
+    if (name === undefined)
+        problems.push({ filePath, message: "the job declaration needs 'name' as a string literal; the generator reads it from the source." });
+    else if (name !== jobName)
+        problems.push({ filePath, message: `the job declaration says name: '${name}' but the file is ${jobName}.ts; the name is the file name.` });
+    if (scriptId === undefined)
+        problems.push({ filePath, message: "the job declaration needs 'scriptId' as a string literal." });
+    if (runParameter === undefined) {
+        problems.push({ filePath, message: "the job declaration needs 'runParameter' as a string literal: the script parameter the run id is passed in." });
+    }
+    if (deployments === undefined) {
+        problems.push({ filePath, message: "the job declaration needs 'deployments' as an array of string literals: every deployment a run may be started on." });
+    }
+    else if (deployments.length === 0) {
+        problems.push({ filePath, message: "'deployments' is empty; a job needs at least one deployment to run on." });
+    }
+    if (!hasProperty(declaration, 'runs')) {
+        problems.push({ filePath, message: "the job declaration needs 'runs: jobRuns', the run record from the generated scripts map; the stages read the run through it." });
+    }
+    const readParametersResult = readParameters(declaration, filePath);
+    problems.push(...readParametersResult.problems);
+    if (problems.length > 0 || scriptId === undefined || runParameter === undefined || deployments === undefined)
+        return { problems };
+    return { script: { scriptId, deployments, runParameter, parameters: readParametersResult.parameters }, problems };
+}
+function readStages(literal, filePath, sourceFile) {
+    const problems = [];
+    const stages = [];
+    let inputType;
+    let resultType;
+    for (const property of literal.properties) {
+        const stageName = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined;
+        if (stageName === undefined || !JOB_STAGE_NAMES.includes(stageName)) {
+            problems.push({ filePath, message: `'${stageName ?? 'a stage'}' is not a stage; a job declares ${JOB_STAGE_NAMES.join(', ')}.` });
+            continue;
+        }
+        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: `stage '${stageName}' must be an inline function; a reference to a function elsewhere carries no types the generator can read.` });
+            continue;
+        }
+        stages.push(stageName);
+        if (stageName === 'getInputData') {
+            const parameter = handler.parameters[0];
+            if (parameter && !parameter.type) {
+                problems.push({ filePath, message: "getInputData has no type on its first parameter; a run's input shape is read from it." });
+            }
+            inputType = parameter?.type?.getText(sourceFile);
+        }
+        if (stageName === 'summarize') {
+            if (!handler.type)
+                problems.push({ filePath, message: "summarize has no return type annotation; a run's result shape is read from it." });
+            resultType = handler.type?.getText(sourceFile);
+        }
+    }
+    if (!stages.includes('getInputData'))
+        problems.push({ filePath, message: 'a job declares getInputData; it is what NetSuite asks for the run\'s work.' });
+    if (!stages.includes('map') && !stages.includes('reduce')) {
+        problems.push({ filePath, message: 'a job declares a map stage, a reduce stage, or both; NetSuite has nothing to run otherwise.' });
+    }
+    return { stages, inputType, resultType, problems };
+}
+export function readJobContract(filePath, source, options) {
+    const problems = [];
+    const fileName = nodePath.basename(toPosixPath(filePath));
+    const nameMatch = jobFileNamePattern.exec(fileName);
+    if (!nameMatch)
+        return { problems: [{ filePath, message: 'a job file is named <name>.ts, with <name> in camelCase; nothing else lives in the jobs folder.' }] };
+    const name = nameMatch[1];
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const header = readScriptTypeHeader(source);
+    if (header !== JOB_SCRIPT_TYPE_HEADER) {
+        problems.push({ filePath, message: `the leading JSDoc says '@NScriptType ${header ?? '(none)'}'; a job is a ${JOB_SCRIPT_TYPE_HEADER}.` });
+    }
+    const carriedTypeImports = [];
+    const inlinedTypeImports = [];
+    const typeDeclarations = [];
+    let contract;
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const result = readTypeImport(statement, filePath, options);
+            problems.push(...result.problems);
+            if (result.read?.kind === 'carried')
+                carriedTypeImports.push(result.read.typeImport);
+            else if (result.read?.kind === 'inlined')
+                inlinedTypeImports.push(result.read.typeImport);
+            else if (result.read?.kind === 'controller') {
+                problems.push({ filePath, message: 'a job does not take types from a controller; its input and result are its own, or a service\'s.' });
+            }
+            continue;
+        }
+        if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) {
+            if (!hasExportModifier(statement)) {
+                problems.push({ filePath, message: `'${statement.name.text}' is not exported; the generator copies the shapes a run's result names into the browser's module as they are written, so export them.` });
+                continue;
+            }
+            if (statement.name.text === GENERATED_JOB_RESULT_TYPE_NAME) {
+                problems.push({ filePath, message: `type '${statement.name.text}' is the name the generated module gives the run's result; call this shape something else.` });
+                continue;
+            }
+            const jsDoc = readLeadingJsDoc(statement, sourceFile);
+            typeDeclarations.push({ name: statement.name.text, text: `${jsDoc ? `${jsDoc}\n` : ''}${statement.getText(sourceFile)}` });
+            continue;
+        }
+        if (!ts.isVariableStatement(statement))
+            continue;
+        const found = findDefineJobCall(statement);
+        if (!found)
+            continue;
+        if (contract) {
+            problems.push({ filePath, message: 'a job file has one defineJob call; a second one is a second script.' });
+            continue;
+        }
+        if (!hasExportModifier(statement) || !found.destructured) {
+            problems.push({ filePath, message: "the stages are exported from the call: `export const { getInputData, map, summarize } = defineJob({ ... }, { ... })`; NetSuite looks for those exports." });
+        }
+        const [declarationArgument, stagesArgument] = found.call.arguments;
+        if (!declarationArgument || !ts.isObjectLiteralExpression(declarationArgument)) {
+            problems.push({ filePath, message: 'defineJob takes the job declaration as an object literal written inline.' });
+            continue;
+        }
+        if (!stagesArgument || !ts.isObjectLiteralExpression(stagesArgument)) {
+            problems.push({ filePath, message: 'defineJob takes the stages as an object literal written inline, each stage a function with its types annotated.' });
+            continue;
+        }
+        const declared = readJobDeclaration(declarationArgument, name, filePath);
+        problems.push(...declared.problems);
+        const stages = readStages(stagesArgument, filePath, sourceFile);
+        problems.push(...stages.problems);
+        for (const exported of found.exportedStages) {
+            if (!JOB_STAGE_NAMES.includes(exported)) {
+                problems.push({ filePath, message: `'${exported}' is not a stage, so NetSuite has no entry point by that name; export ${JOB_STAGE_NAMES.join(', ')}.` });
+            }
+            else if (exported !== 'summarize' && !stages.stages.includes(exported)) {
+                problems.push({ filePath, message: `'${exported}' is exported but not declared; a stage exported without a declaration throws when NetSuite calls it.` });
+            }
+        }
+        for (const stage of stages.stages) {
+            if (!found.exportedStages.includes(stage)) {
+                problems.push({ filePath, message: `stage '${stage}' is declared but not exported; NetSuite only runs the stages the file exports.` });
+            }
+        }
+        // The run is closed in summarize, so a job that leaves it out would leave every run of it looking unfinished.
+        if (!found.exportedStages.includes('summarize')) {
+            problems.push({ filePath, message: 'every job exports summarize, declared or not: it is where the run is closed and its result written.' });
+        }
+        if (!declared.script)
+            continue;
+        contract = { name, filePath, script: declared.script, inputType: stages.inputType, resultType: stages.resultType, stages: stages.stages, exportedStages: found.exportedStages };
+    }
+    if (!contract) {
+        if (problems.length === 0) {
+            problems.push({ filePath, message: 'must declare its script: `export const { getInputData, map, summarize } = defineJob({ name, scriptId, deployments, runParameter, runs }, { ... })`.' });
+        }
+        return { problems };
+    }
+    if (problems.length > 0)
+        return { problems };
+    return { contract: { ...contract, carriedTypeImports, inlinedTypeImports, typeDeclarations }, problems };
+}