@codenotch/codenotch.cli 1.0.36 → 1.0.37

package/dist/utils/ProjectUtils.d.ts

@@ -1,5 +1,140 @@
 import { CompilationResult } from './ProjectCompilationUtils';
-import { ICodenotchProjectManifest } from '@codenotch/codenotch.core';
+import { LiteralValue } from './ScriptDeclarationUtils';
+import { IJsonSchema } from './TypeSchemaUtils';
+import { IAppManifest, ICodenotchProjectManifest } from '@codenotch/codenotch.core';
+/** A *.i18n.csv file found in a project */
+export interface IDiscoveredI18n {
+    /** Absolute path of the file */
+    filePath: string;
+    /** Translation keys it declares, in file order. Empty when its header has no 'key' column */
+    keys: string[];
+    /** Languages of its columns, e.g. ['en', 'de'] */
+    languages: string[];
+}
+/** A call applied to the type of a column, e.g. `.default('')` or `.primary()` */
+export interface IColumnModifier {
+    name: string;
+    arguments: LiteralValue[];
+}
+/** A column of a table, read from `fullName: p.string()` */
+export interface ITableColumn {
+    /** Name of the column, e.g. 'fullName' */
+    name: string;
+    /** Type it is built with, e.g. 'string', 'integer', 'text' */
+    type?: string;
+    /** Arguments given to the type itself, e.g. the 255 of p.string(255) */
+    typeArguments: LiteralValue[];
+    /** True when '.primary()' is applied */
+    isPrimary: boolean;
+    /** Value given to '.default(...)' when it is a literal */
+    defaultValue?: LiteralValue;
+    /** Every call applied after the type, in source order */
+    modifiers: IColumnModifier[];
+}
+/** A `defineEntity({ ... })` declaration found in a project */
+export interface IDiscoveredTable {
+    /** Absolute path of the script declaring it */
+    filePath: string;
+    /** Value of its 'name' property, e.g. 'User' */
+    name?: string;
+    /** False when the table has a name that is built at runtime, so it cannot be known from the sources */
+    isNameStatic: boolean;
+    /** Name of the variable it is assigned to, e.g. 'User' */
+    variableName?: string;
+    /** True when that variable is exported */
+    isExported: boolean;
+    /** 1-based line of the declaration, to point at it in a diagnostic */
+    line: number;
+    /** Columns of the table, in source order */
+    columns: ITableColumn[];
+    /** Name of its exported row type, e.g. 'IUser' from `export type IUser = InferEntity<typeof User>` */
+    typeName?: string;
+    /**
+     * Line to paste to use that type, with a path relative to the root of the project, e.g.
+     * "import { IUser } from './tables/user';". Use {@link ProjectUtils.getTableTypeImport}
+     * to get it relative to another file.
+     */
+    importStatement?: string;
+    /** Every property written literally, for whatever is not covered by the fields above */
+    properties: Record<string, LiteralValue>;
+}
+/** A field of a document. Same shape as a table column, since both are declared the same way */
+export type IDocumentField = ITableColumn;
+/** A `defineDocument({ ... })` declaration found in a project */
+export interface IDiscoveredDocument extends Omit<IDiscoveredTable, 'columns'> {
+    /** Fields of the document, in source order */
+    fields: IDocumentField[];
+}
+/** A React app found in a project: a tsx/jsx script and its sibling manifest */
+export interface IDiscoveredApp {
+    /** Absolute path of the '<App>.manifest.json' */
+    manifestPath: string;
+    /** Absolute path of the '<App>.tsx' or '<App>.jsx' */
+    scriptPath: string;
+    /** Syntax of the script */
+    type: 'jsx' | 'tsx';
+    /** Name shared by both files, e.g. 'Dashboard' for 'Dashboard.tsx' */
+    name: string;
+    /** Content of the manifest, empty when it cannot be parsed */
+    manifest: IAppManifest;
+}
+/** How a process is started, read from its `trigger` property */
+export type IProcessTrigger = 
+/** trigger: api.post('/books') */
+{
+    kind: 'api';
+    method: string;
+    route: string;
+}
+/** trigger: timer('0 8 * * *') */
+ | {
+    kind: 'timer';
+    cron: string;
+}
+/** trigger: signal('book.returned') */
+ | {
+    kind: 'signal';
+    ref: string;
+}
+/** trigger: install({ once: true }) */
+ | {
+    kind: 'install';
+    options: Record<string, LiteralValue>;
+}
+/** A trigger that is not one of the known factories, or that is built at runtime */
+ | {
+    kind: 'unknown';
+    callee: string;
+};
+/** A `process({ ... })` declaration found in a project */
+export interface IDiscoveredProcess {
+    /** Absolute path of the script declaring it */
+    filePath: string;
+    /** Value of its 'id', undefined when absent or computed (see isIdStatic) */
+    id?: string;
+    /** False when the process has an id that is built at runtime, so it cannot be known from the sources */
+    isIdStatic: boolean;
+    /** Name of the variable it is assigned to, e.g. 'createBook' */
+    variableName?: string;
+    /** True when that variable is exported, which a process needs to be reachable */
+    isExported: boolean;
+    /** 1-based line of the declaration, to point at it in a diagnostic */
+    line: number;
+    /** Value of 'auth.scope', e.g. 'internal' or 'system' */
+    scope?: string;
+    /** How it is started, undefined when it has no trigger and is only reachable through ctx.call */
+    trigger?: IProcessTrigger;
+    /** True when 'run' declares a second parameter, whether or not it is typed */
+    takesInput: boolean;
+    /** Schema of the second parameter of 'run' (its input), when it carries a type annotation */
+    input?: IJsonSchema;
+    /** Schema of the declared return type of 'run', `Promise<T>` unwrapped, when it carries one */
+    output?: IJsonSchema;
+    /** Literal 'description' of the declaration, when any */
+    description?: string;
+    /** Every property written literally, for whatever is not covered by the fields above */
+    properties: Record<string, LiteralValue>;
+}
 export default abstract class ProjectUtils {
     /**
      * Compile and package the project to prepare it for deployment
@@ -7,9 +142,87 @@ export default abstract class ProjectUtils {
      * Output a zip file that can be deployed to Codenotch
      */
     static packageProject(sourcePath: string, outputPath: string, ignoreErrors?: boolean): Promise<CompilationResult>;
-    static isManifestCompiled(projectPath: string): Promise<boolean>;
     private static getCollectionCount;
     static getManifest(projectPath: string): Promise<ICodenotchProjectManifest>;
     static getProjectServiceName(projectPath: string): Promise<string>;
-    static inspectProject(projectPath: string): Promise<void>;
+    static inspectProject(projectPath: string): Promise<{
+        manifest: ICodenotchProjectManifest | undefined;
+        processes: IDiscoveredProcess[];
+        tables: IDiscoveredTable[];
+        documents: IDiscoveredDocument[];
+        apps: IDiscoveredApp[];
+        i18ns: IDiscoveredI18n[];
+        pkgJson: {
+            name?: string;
+            version?: string;
+        } | undefined;
+    }>;
+    /** Short human readable form of a process trigger, e.g. 'POST /books' or 'cron 0 8 * * *' */
+    private static describeTrigger;
+    /**
+     * Find all file (recursivly) in a given folder (workspacePath) that contains a table declaration ('defineEntity').
+     */
+    static discoverTableFiles(workspacePath: string): Promise<IDiscoveredTable[]>;
+    /**
+     * Shared by the tables and the documents, which only differ by the factory they are declared with
+     *
+     * @param factoryName 'defineEntity' or 'defineDocument'
+     * @param typeHelperNames helpers building their row type, e.g. ['InferEntity']
+     */
+    private static discoverOrmDeclarations;
+    /**
+     * Line to paste to use the type of a table from another file, e.g.
+     * "import { IUser } from '../tables/user';"
+     *
+     * @param table table to import the type of
+     * @param fromFilePath file the import would be written in
+     */
+    static getTableTypeImport(table: IDiscoveredTable, fromFilePath: string): string | undefined;
+    private static buildTypeImport;
+    /**
+     * Turns the `properties` of a table into columns: `bio: p.text().default('')` gives the
+     * type 'text' and the modifier 'default' with its value.
+     */
+    private static readColumns;
+    /**
+     * Find all file (recursivly) in a given folder (workspacePath) that contains a document declaration ('defineDocument').
+     */
+    static discoverDocumentFiles(workspacePath: string): Promise<IDiscoveredDocument[]>;
+    /**
+     * Line to paste to use the type of a document from another file, e.g.
+     * "import { ISettings } from '../documents/settings';"
+     *
+     * @param document document to import the type of
+     * @param fromFilePath file the import would be written in
+     */
+    static getDocumentTypeImport(document: IDiscoveredDocument, fromFilePath: string): string | undefined;
+    /**
+     * Find all file (recursivly) in a given folder (workspacePath) that contains a table declaration ('process').
+     */
+    static discoverProcessFiles(workspacePath: string): Promise<IDiscoveredProcess[]>;
+    /** Value of `auth: { scope: 'internal' }` when it is written literally */
+    private static readScope;
+    /**
+     * Turns the `trigger` property into something usable, e.g. `api.post('/books')` into
+     * { kind: 'api', method: 'POST', route: '/books' }.
+     * A process without trigger is only reachable through ctx.call, and returns undefined.
+     */
+    private static readTrigger;
+    private static getAllScriptFile;
+    /**
+     * An app is a tsx/jsx file with a sibling *.manifest.json.
+     *
+     * A script without its manifest is not an app and is left out, whereas an app whose manifest
+     * cannot be parsed is still reported, with an empty manifest: it exists on disk, and saying
+     * why its manifest is wrong is the job of the validators.
+     */
+    static discoverAppsFiles(workspacePath: string): Promise<IDiscoveredApp[]>;
+    /**
+     * Find all *.i18n.csv files (recursively) in a given folder (workspacePath), with the keys
+     * they declare and the languages they translate them into.
+     *
+     * A file whose first column is not 'key' is reported with no key and no language rather than
+     * being read wrong: saying why it is malformed is the job of the validators.
+     */
+    static discoverI18nsFiles(workspacePath: string): Promise<IDiscoveredI18n[]>;
 }

package/dist/utils/ProjectUtils.js

@@ -9,6 +9,20 @@ const node_os_1 = __importDefault(require("node:os"));
 const promises_1 = __importDefault(require("node:fs/promises"));
 const FileUtils_1 = __importDefault(require("./FileUtils"));
 const ProjectCompilationUtils_1 = __importDefault(require("./ProjectCompilationUtils"));
+const ScriptDeclarationUtils_1 = __importDefault(require("./ScriptDeclarationUtils"));
+const I18nTsUtils_1 = __importDefault(require("./I18nTsUtils"));
+const papaparse_1 = __importDefault(require("papaparse"));
+/** Module the process factories are imported from */
+const PROCESS_MODULE = '@codenotch/process';
+/** Module the table factories are imported from */
+const ORM_MODULE = '@codenotch/orm';
+/** Property of a table declaration holding its columns */
+const TABLE_COLUMNS_PROPERTY = 'properties';
+/**
+ * Helpers a document row type can be built with. 'InferDocument' is the counterpart of
+ * 'InferEntity', and the latter is accepted too in case both kinds share the same helper.
+ */
+const DOCUMENT_TYPE_HELPERS = ['InferDocument', 'InferEntity'];
 class ProjectUtils {
     /**
      * Compile and package the project to prepare it for deployment
@@ -32,7 +46,7 @@ class ProjectUtils {
                 console.warn(chalk_1.default.yellow("Ignoring compilation errors and proceeding with packaging..."));
             }
             // Zip the project folder
-            await FileUtils_1.default.zipFolder(tempRoot, outputPath);
+            FileUtils_1.default.zipFolder(tempRoot, outputPath);
             return compilation;
         }
         catch (e) {
@@ -40,14 +54,14 @@ class ProjectUtils {
         }
         finally {
             // Clean up temp folder
-            await FileUtils_1.default.delete(tempRoot);
+            await FileUtils_1.default.deleteRecursively(tempRoot);
         }
     }
     // Check if the manifest is full (meaning with process, apps, etc...) or if it's a minimal manifest that only contains metadata, this can be used to determine if the project has been compiled or not
-    static async isManifestCompiled(projectPath) {
-        const manifest = await ProjectUtils.getManifest(projectPath);
+    /*static async isManifestCompiled(projectPath: string): Promise<boolean> {
+        const manifest = await ProjectUtils.getManifest(projectPath) as IExtendedScenarioProjectManifest;
         return !!(manifest.processes);
-    }
+    }*/
     static getCollectionCount(value) {
         return Array.isArray(value) ? value.length : 0;
     }
@@ -62,24 +76,375 @@ class ProjectUtils {
         return manifest.serviceName ?? manifest.projectName.toLowerCase();
     }
     static async inspectProject(projectPath) {
-        //TODO will only work on a compiler project since we rely on the full manifest
-        const manifest = await ProjectUtils.getManifest(projectPath);
-        const projectName = manifest.projectName || "(unknown)";
-        const serviceName = manifest.serviceName || projectName.toLowerCase();
-        const version = manifest.version || "(unknown)";
-        const index = manifest.index || "(not set)";
-        const languages = ProjectUtils.getCollectionCount(manifest.languages);
-        const roles = ProjectUtils.getCollectionCount(manifest.roles);
         console.log(chalk_1.default.blue("Project inspection"));
-        console.log(`${chalk_1.default.gray("Path:")} ${node_path_1.default.resolve(projectPath)}`);
-        console.log(`${chalk_1.default.gray("Project:")} ${chalk_1.default.cyan(projectName)}`);
-        console.log(`${chalk_1.default.gray("Service:")} ${chalk_1.default.cyan(serviceName)}`);
-        console.log(`${chalk_1.default.gray("Version:")} ${chalk_1.default.cyan(version)}`);
-        console.log(`${chalk_1.default.gray("Index:")} ${chalk_1.default.cyan(index)}`);
-        console.log("");
-        console.log(chalk_1.default.blue("Manifest metadata"));
-        console.log(`- languages: ${chalk_1.default.yellow(languages.toString())}`);
-        console.log(`- roles: ${chalk_1.default.yellow(roles.toString())}`);
+        let manifest;
+        try {
+            manifest = await ProjectUtils.getManifest(projectPath);
+            const projectName = manifest.projectName || "(unknown)";
+            const serviceName = manifest.serviceName || projectName.toLowerCase();
+            const version = manifest.version || "(unknown)";
+            const index = manifest.index || "(not set)";
+            const languages = ProjectUtils.getCollectionCount(manifest.languages);
+            const roles = ProjectUtils.getCollectionCount(manifest.roles);
+            console.log(`${chalk_1.default.gray("Path:")} ${node_path_1.default.resolve(projectPath)}`);
+            console.log(`${chalk_1.default.gray("Project:")} ${chalk_1.default.cyan(projectName)}`);
+            console.log(`${chalk_1.default.gray("Service:")} ${chalk_1.default.cyan(serviceName)}`);
+            console.log(`${chalk_1.default.gray("Version:")} ${chalk_1.default.cyan(version)}`);
+            console.log(`${chalk_1.default.gray("Index:")} ${chalk_1.default.cyan(index)}`);
+            console.log("");
+            console.log(chalk_1.default.blue("Manifest metadata"));
+            console.log(`- languages: ${chalk_1.default.yellow(languages.toString())}`);
+            console.log(`- roles: ${chalk_1.default.yellow(roles.toString())}`);
+        }
+        catch {
+            console.log(`- manifest.json not found.`);
+            console.log(`${chalk_1.default.gray("Path:")} unknown`);
+            console.log(`${chalk_1.default.gray("Project:")} unknown`);
+            console.log(`${chalk_1.default.gray("Service:")} unknown`);
+            console.log(`${chalk_1.default.gray("Version:")} unknown`);
+            console.log(`${chalk_1.default.gray("Index:")} unknown`);
+            console.log("");
+            console.log(chalk_1.default.blue("Manifest metadata"));
+            console.log(`- languages: unknown`);
+            console.log(`- roles: unknown`);
+        }
+        // Find ./package.json
+        const pkgJson = await FileUtils_1.default.readJsonFileAsync(node_path_1.default.join(projectPath, 'package.json'));
+        if (pkgJson) {
+            console.log(`- package.json found:`);
+            console.log(`\tname: ${chalk_1.default.cyan(pkgJson.name ?? "(not set)")}`);
+            console.log(`\tversion: ${chalk_1.default.cyan(pkgJson.version ?? "(not set)")}`);
+        }
+        else {
+            console.log(`- package.json not found.`);
+        }
+        // Paths are printed relative to the project, absolute ones would push the useful part off screen
+        const relativeToProject = (filePath) => node_path_1.default.relative(node_path_1.default.resolve(projectPath), filePath) || filePath;
+        // Find processes
+        const processes = await ProjectUtils.discoverProcessFiles(projectPath);
+        if (processes.length === 0) {
+            console.log(`- processes: No process discovered.`);
+        }
+        else {
+            console.log(`- processes: ${processes.length}`);
+            for (const p of processes) {
+                const name = p.id ?? chalk_1.default.yellow("(computed id)");
+                const trigger = ProjectUtils.describeTrigger(p.trigger);
+                console.log(`\t${chalk_1.default.cyan(name)} ${chalk_1.default.gray(trigger)} at ${relativeToProject(p.filePath)}:${p.line}`);
+            }
+        }
+        // Find tables
+        const tables = await ProjectUtils.discoverTableFiles(projectPath);
+        if (tables.length === 0) {
+            console.log(`- tables: No table discovered.`);
+        }
+        else {
+            console.log(`- tables: ${tables.length}`);
+            for (const t of tables) {
+                const name = t.name ?? chalk_1.default.yellow("(computed name)");
+                const columns = `${t.columns.length} column${t.columns.length === 1 ? '' : 's'}`;
+                console.log(`\t${chalk_1.default.cyan(name)} ${chalk_1.default.gray(columns)} at ${relativeToProject(t.filePath)}:${t.line}`);
+            }
+        }
+        // Find documents
+        const documents = await ProjectUtils.discoverDocumentFiles(projectPath);
+        if (documents.length === 0) {
+            console.log(`- documents: No table discovered.`);
+        }
+        else {
+            console.log(`- documents: ${documents.length}`);
+            for (const d of documents) {
+                const name = d.name ?? chalk_1.default.yellow("(computed name)");
+                const columns = `${d.fields.length} column${d.fields.length === 1 ? '' : 's'}`;
+                console.log(`\t${chalk_1.default.cyan(name)} ${chalk_1.default.gray(columns)} at ${relativeToProject(d.filePath)}:${d.line}`);
+            }
+        }
+        // Find apps
+        const apps = await ProjectUtils.discoverAppsFiles(projectPath);
+        if (apps.length === 0) {
+            console.log(`- apps: No app discovered.`);
+        }
+        else {
+            console.log(`- apps: ${apps.length}`);
+            for (const a of apps) {
+                const title = a.manifest.app?.name ?? a.manifest.html?.title ?? "(untitled)";
+                console.log(`\t${chalk_1.default.cyan(a.name)} ${chalk_1.default.gray(`${a.type}, ${title}`)} at ${relativeToProject(a.scriptPath)}`);
+            }
+        }
+        // Find i18ns
+        const i18ns = await ProjectUtils.discoverI18nsFiles(projectPath);
+        if (i18ns.length === 0) {
+            console.log(`- i18ns: No i18ns file discovered.`);
+        }
+        else {
+            console.log(`- i18ns: ${i18ns.length}`);
+            for (const a of i18ns) {
+                console.log(`\t${chalk_1.default.cyan(a.keys.length)} keys (${chalk_1.default.gray(`${a.languages.length}`)} langs) at ${relativeToProject(a.filePath)}`);
+            }
+        }
+        // Could be usefull so returns all
+        return {
+            manifest,
+            processes,
+            tables,
+            documents,
+            apps,
+            i18ns,
+            pkgJson
+        };
+    }
+    /** Short human readable form of a process trigger, e.g. 'POST /books' or 'cron 0 8 * * *' */
+    static describeTrigger(trigger) {
+        switch (trigger?.kind) {
+            case 'api': return `${trigger.method} ${trigger.route}`;
+            case 'timer': return `cron ${trigger.cron}`;
+            case 'signal': return `signal ${trigger.ref}`;
+            case 'install': return 'on install';
+            case 'unknown': return `trigger ${trigger.callee}`;
+            default: return 'no trigger';
+        }
+    }
+    /**
+     * Find all file (recursivly) in a given folder (workspacePath) that contains a table declaration ('defineEntity').
+     */
+    static async discoverTableFiles(workspacePath) {
+        return await this.discoverOrmDeclarations(workspacePath, 'defineEntity', ['InferEntity']);
+    }
+    /**
+     * Shared by the tables and the documents, which only differ by the factory they are declared with
+     *
+     * @param factoryName 'defineEntity' or 'defineDocument'
+     * @param typeHelperNames helpers building their row type, e.g. ['InferEntity']
+     */
+    static async discoverOrmDeclarations(workspacePath, factoryName, typeHelperNames) {
+        const files = await this.getAllScriptFile(workspacePath);
+        const results = [];
+        for (const filePath of files) {
+            const content = await FileUtils_1.default.readFileAsync(filePath);
+            // Cheap way out: a file that does not even name the module declares nothing
+            if (!content || !content.includes(ORM_MODULE)) {
+                continue;
+            }
+            const analysis = ScriptDeclarationUtils_1.default.analyzeScript(filePath, content, ORM_MODULE, [factoryName], typeHelperNames);
+            for (const declaration of analysis.declarations) {
+                // 'export type IUser = InferEntity<typeof User>' next to 'export const User = defineEntity(...)'
+                const typeAlias = analysis.typeAliases.find(alias => alias.targetName === declaration.variableName && alias.isExported);
+                results.push({
+                    filePath,
+                    name: typeof declaration.properties['name'] === 'string' ? declaration.properties['name'] : undefined,
+                    isNameStatic: typeof declaration.properties['name'] === 'string'
+                        || declaration.properties['name'] === undefined,
+                    variableName: declaration.variableName,
+                    isExported: declaration.isExported,
+                    line: declaration.line,
+                    columns: this.readColumns(declaration),
+                    typeName: typeAlias?.name,
+                    importStatement: typeAlias === undefined
+                        ? undefined
+                        : this.buildTypeImport(typeAlias.name, filePath, workspacePath),
+                    properties: declaration.properties
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Line to paste to use the type of a table from another file, e.g.
+     * "import { IUser } from '../tables/user';"
+     *
+     * @param table table to import the type of
+     * @param fromFilePath file the import would be written in
+     */
+    static getTableTypeImport(table, fromFilePath) {
+        if (table.typeName === undefined) {
+            return undefined;
+        }
+        return this.buildTypeImport(table.typeName, table.filePath, node_path_1.default.dirname(fromFilePath));
+    }
+    static buildTypeImport(typeName, targetFilePath, fromFolderPath) {
+        // Module specifiers are posix and carry no extension
+        let specifier = node_path_1.default.relative(fromFolderPath, targetFilePath).replaceAll('\\', '/').replace(/\.[^./]+$/, '');
+        if (!specifier.startsWith('.')) {
+            specifier = `./${specifier}`;
+        }
+        return `import { ${typeName} } from '${specifier}';`;
+    }
+    /**
+     * Turns the `properties` of a table into columns: `bio: p.text().default('')` gives the
+     * type 'text' and the modifier 'default' with its value.
+     */
+    static readColumns(declaration) {
+        const columns = [];
+        for (const [path, call] of Object.entries(declaration.calls)) {
+            // Only the calls of the 'properties' object are columns
+            if (!path.startsWith(`${TABLE_COLUMNS_PROPERTY}.`)) {
+                continue;
+            }
+            const name = path.substring(TABLE_COLUMNS_PROPERTY.length + 1);
+            // p.integer().primary() -> the first step is the type, the next ones are modifiers
+            const [type, ...modifiers] = call.steps;
+            const defaultModifier = modifiers.find(modifier => modifier.name === 'default');
+            columns.push({
+                name,
+                type: type?.name,
+                typeArguments: type?.arguments ?? [],
+                isPrimary: modifiers.some(modifier => modifier.name === 'primary'),
+                defaultValue: defaultModifier?.arguments[0],
+                modifiers: modifiers.map(modifier => ({ name: modifier.name, arguments: modifier.arguments }))
+            });
+        }
+        return columns;
+    }
+    /**
+     * Find all file (recursivly) in a given folder (workspacePath) that contains a document declaration ('defineDocument').
+     */
+    static async discoverDocumentFiles(workspacePath) {
+        const declarations = await this.discoverOrmDeclarations(workspacePath, 'defineDocument', DOCUMENT_TYPE_HELPERS);
+        // A document holds fields rather than columns, everything else is read the same way
+        return declarations.map(({ columns, ...declaration }) => ({ ...declaration, fields: columns }));
+    }
+    /**
+     * Line to paste to use the type of a document from another file, e.g.
+     * "import { ISettings } from '../documents/settings';"
+     *
+     * @param document document to import the type of
+     * @param fromFilePath file the import would be written in
+     */
+    static getDocumentTypeImport(document, fromFilePath) {
+        if (document.typeName === undefined) {
+            return undefined;
+        }
+        return this.buildTypeImport(document.typeName, document.filePath, node_path_1.default.dirname(fromFilePath));
+    }
+    /**
+     * Find all file (recursivly) in a given folder (workspacePath) that contains a table declaration ('process').
+     */
+    static async discoverProcessFiles(workspacePath) {
+        const files = await this.getAllScriptFile(workspacePath);
+        const results = [];
+        for (const filePath of files) {
+            const content = await FileUtils_1.default.readFileAsync(filePath);
+            // Cheap way out: a file that does not even name the module declares no process
+            if (!content || !content.includes(PROCESS_MODULE)) {
+                continue;
+            }
+            for (const declaration of ScriptDeclarationUtils_1.default.findDeclarationCalls(filePath, content, PROCESS_MODULE, ['process'])) {
+                results.push({
+                    filePath,
+                    id: declaration.id,
+                    isIdStatic: declaration.isIdStatic,
+                    variableName: declaration.variableName,
+                    isExported: declaration.isExported,
+                    line: declaration.line,
+                    scope: this.readScope(declaration),
+                    trigger: this.readTrigger(declaration),
+                    // run(ctx, input): the context comes first, the input of the process second
+                    takesInput: (declaration.functions['run']?.parameters.length ?? 0) >= 2,
+                    input: declaration.functions['run']?.parameters[1]?.schema,
+                    output: declaration.functions['run']?.returnSchema,
+                    description: typeof declaration.properties['description'] === 'string' ? declaration.properties['description'] : undefined,
+                    properties: declaration.properties
+                });
+            }
+        }
+        return results;
+    }
+    /** Value of `auth: { scope: 'internal' }` when it is written literally */
+    static readScope(declaration) {
+        const auth = declaration.properties['auth'];
+        if (auth !== null && typeof auth === 'object' && !Array.isArray(auth) && typeof auth['scope'] === 'string') {
+            return auth['scope'];
+        }
+        return undefined;
+    }
+    /**
+     * Turns the `trigger` property into something usable, e.g. `api.post('/books')` into
+     * { kind: 'api', method: 'POST', route: '/books' }.
+     * A process without trigger is only reachable through ctx.call, and returns undefined.
+     */
+    static readTrigger(declaration) {
+        const trigger = declaration.calls['trigger'];
+        if (trigger === undefined) {
+            return undefined;
+        }
+        const [first] = trigger.arguments;
+        if (trigger.callee.startsWith('api.') && typeof first === 'string') {
+            return { kind: 'api', method: trigger.callee.substring('api.'.length).toUpperCase(), route: first };
+        }
+        if (trigger.callee === 'timer' && typeof first === 'string') {
+            return { kind: 'timer', cron: first };
+        }
+        if (trigger.callee === 'signal' && typeof first === 'string') {
+            return { kind: 'signal', ref: first };
+        }
+        if (trigger.callee === 'install') {
+            const options = first !== null && typeof first === 'object' && !Array.isArray(first) ? first : {};
+            return { kind: 'install', options };
+        }
+        // A trigger that is not one of the known factories, or built at runtime: reported as is rather than guessed
+        return { kind: 'unknown', callee: trigger.callee };
+    }
+    static async getAllScriptFile(workspacePath, fileExtensions = ['.tsx', '.jsx', '.ts', '.js']) {
+        const ignoredFolders = await FileUtils_1.default.getIgnoredFolderPaths(workspacePath);
+        const results = FileUtils_1.default.listFilesRecursively(workspacePath, {
+            ignoredFolderPaths: ignoredFolders,
+            fileExtensions: fileExtensions
+        });
+        return results;
+    }
+    /**
+     * An app is a tsx/jsx file with a sibling *.manifest.json.
+     *
+     * A script without its manifest is not an app and is left out, whereas an app whose manifest
+     * cannot be parsed is still reported, with an empty manifest: it exists on disk, and saying
+     * why its manifest is wrong is the job of the validators.
+     */
+    static async discoverAppsFiles(workspacePath) {
+        const files = await this.getAllScriptFile(workspacePath, ['.tsx', '.jsx']);
+        const results = [];
+        for (const scriptPath of files) {
+            // 'apps/Dashboard.tsx' is an app when 'apps/Dashboard.manifest.json' sits next to it
+            const appName = FileUtils_1.default.getNameFromPath(scriptPath, true);
+            const manifestPath = node_path_1.default.join(node_path_1.default.dirname(scriptPath), `${appName}.manifest.json`);
+            if (await FileUtils_1.default.exists(manifestPath) === false) {
+                continue;
+            }
+            results.push({
+                manifestPath,
+                scriptPath,
+                type: FileUtils_1.default.getExtensionFromPath(scriptPath).toLowerCase() === 'jsx' ? 'jsx' : 'tsx',
+                name: appName,
+                manifest: await FileUtils_1.default.readJsonFileAsync(manifestPath) ?? {}
+            });
+        }
+        return results;
+    }
+    /**
+     * Find all *.i18n.csv files (recursively) in a given folder (workspacePath), with the keys
+     * they declare and the languages they translate them into.
+     *
+     * A file whose first column is not 'key' is reported with no key and no language rather than
+     * being read wrong: saying why it is malformed is the job of the validators.
+     */
+    static async discoverI18nsFiles(workspacePath) {
+        const files = FileUtils_1.default.listFilesRecursively(workspacePath, {
+            ignoredFolderPaths: await FileUtils_1.default.getIgnoredFolderPaths(workspacePath),
+            fileExtensions: ['.i18n.csv']
+        });
+        const results = [];
+        for (const filePath of files) {
+            const content = await FileUtils_1.default.readFileAsync(filePath);
+            if (content === undefined) {
+                continue;
+            }
+            const parsed = papaparse_1.default.parse(content, { header: true, skipEmptyLines: 'greedy' });
+            const columns = parsed.meta.fields ?? [];
+            // Languages come from the header rather than from the rows, so an empty file still reports them
+            const languages = columns[0] === 'key' ? columns.slice(1).filter(column => column.trim() !== '') : [];
+            const keys = columns[0] === 'key' ? I18nTsUtils_1.default.getEntries(parsed.data).map(entry => entry.key) : [];
+            results.push({ filePath, keys, languages });
+        }
+        return results;
     }
 }
 exports.default = ProjectUtils;