@izara_project/izara-core-generate-service-code 1.0.65 → 1.0.66

package/src/generate.js

@@ -1,130 +1,64 @@
-/*
-Copyright (C) 2020 Sven Mason <http://izara.io>
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <http://www.gnu.org/licenses/>.
-*/
-
-import { join } from 'path';
-import { validator } from '@izara_project/izara-core-library-service-schemas';
-import { basicValidatorSchema } from '@izara_project/izara-shared-service-schemas';
-import { generateCode } from './generateCode.js';
-import { generateSchema } from './generateSchema.js';
-
-const { validateLocalSchema } = validator;
-
-/**
- * High-level API to validate schemas and generate code.
- * Wires legacy Logger and validateLocalSchema.
- *
- * @param {string} rootPath - The root path of the project.
- * @param {object} [options={}] - Configuration options.
- * @param {object} [options.logger] - Logger instance.
- * @param {string} [options.configPath] - Path to the serverless configuration file.
- * @param {string} [options.outputPath] - Output directory path.
- * @param {boolean} [options.skipValidation=false] - Whether to skip schema validation.
- * @param {boolean} [options.skipGenerateSchema=false] - Whether to skip schema generation.
- * @param {boolean} [options.skipGenerateCode=false] - Whether to skip code generation.
- * @param {Array} [options.schemaTemplateConfig] - Schema template configuration.
- * @returns {Promise<{durationMs: number}>} Generation duration details.
- */
-async function generate(rootPath, options = {}) {
-  const {
-    logger = createSilentLogger(),
-    configPath = join(rootPath, 'config', 'serverless.config.yml'),
-    outputPath = rootPath,
-    skipValidation = false,
-    skipGenerateSchema = false,
-    skipGenerateCode = false,
-    schemaTemplateConfig
-  } = options;
-
-  const schemasPath = join(rootPath, 'app', 'src', 'schemas');
-
-  if (!skipGenerateSchema) {
-    await generateSchema(rootPath, {
-      configPath,
-      outputPath,
-      schemaTemplateConfig
-    });
-  }
-
-  if (!skipValidation) {
-    patchFlowStepsValidationSchema();
-
-    console.info('[INFO] [generate] STATUS=VALIDATING | local schemas...');
-    const validateStartTime = Date.now();
-    const result = await validateLocalSchema({ logger }, schemasPath, configPath);
-    const validateDuration = Date.now() - validateStartTime;
-
-    console.info(
-      `[INFO] [generate] STATUS=VALIDATED | errors=${result.validateErrors.length} | elapsedMs=${validateDuration}`
-    );
-
-    if (result.validateErrors.length > 0) {
-      logger.error(
-        'Validation failed with following errors:',
-        result.validateErrors
-      );
-      const err = new Error('Schema validation failed');
-      err.validateErrors = result.validateErrors;
-      throw err;
-    }
-  }
-
-  if (skipGenerateCode) {
-    return { durationMs: 0 };
+import { buildGenerationPlan } from './plan/buildGenerationPlan.js';
+import { commitArtifacts } from './output/commitArtifacts.js';
+import { compileProject } from './compile/compileProject.js';
+import { crudApplicationManagedPaths, emitCrudApplicationArtifacts } from './emit/crud/emitCrudApplicationArtifacts.js';
+import { dynamicCrudFlowSchemaPaths, emitDynamicCrudFlowSchemas } from './emit/crud/emitDynamicCrudFlowSchemas.js';
+import { customFlowApplicationManagedPaths, emitCustomFlowApplicationArtifacts } from './emit/custom/emitCustomFlowApplicationArtifacts.js';
+import { emitDynamicRbacFlowSchemas, rbacFlowSchemaManagedPaths } from './emit/rbac/emitDynamicRbacFlowSchemas.js';
+import { emitRbacApplicationArtifacts, rbacApplicationManagedPaths } from './emit/rbac/emitRbacApplicationArtifacts.js';
+import { dynamicRelationshipFlowSchemaPaths, emitDynamicRelationshipFlowSchemas } from './emit/relationship/emitDynamicRelationshipFlowSchemas.js';
+import { emitRelationshipApplicationArtifacts, relationshipApplicationManagedPaths } from './emit/relationship/emitRelationshipApplicationArtifacts.js';
+import { emitResourceArtifacts, resourceArtifactPaths } from './emit/resource/emitResourceArtifacts.js';
+import { loadLocalSchemaDirectory } from './compile/loadSchemas.js';
+import { emitSystemWebSocketArtifacts, hasSystemWebSocket, systemWebSocketManagedPaths } from './emit/system/emitSystemWebSocketArtifacts.js';
+
+export async function generate(rootPath, options = {}) {
+  const startedAt = Date.now();
+  const logger = options.logger;
+  logger?.info?.(`[INFO] [Generate] STATUS=STARTED | rootPath=${rootPath}`);
+  try {
+    const project = compileProject({ ...options, rootPath });
+    const [objects, relationships, flows] = await Promise.all([
+      loadLocalSchemaDirectory(project, 'ObjectSchemas'),
+      loadLocalSchemaDirectory(project, 'RelationshipSchemas'),
+      loadLocalSchemaDirectory(project, 'FlowSchemas')
+    ]);
+    logger?.debug?.(`[DEBUG] [Generate] STATUS=SCHEMAS_LOADED | objects=${objects.length} relationships=${relationships.length} flows=${flows.length}`);
+    const groups = await emitGroups({ project, objects, relationships, flows });
+    logger?.debug?.(`[DEBUG] [Generate] STATUS=ARTIFACTS_EMITTED | ${groups.map(group => `${group.scope}=${group.artifacts.length}`).join(' ')}`);
+    const files = groups.length === 0
+      ? []
+      : await commitArtifacts(buildGenerationPlan(project, groups.flatMap(group => group.artifacts), {
+        managedScopes: Object.fromEntries(groups.map(group => [group.scope, group.managedPaths]))
+      }));
+    const durationMs = Date.now() - startedAt;
+    logger?.info?.(`[INFO] [Generate] STATUS=FINISHED | files=${files.length} durationMs=${durationMs}`);
+
+    return { project, durationMs, files };
+  } catch (error) {
+    logger?.error?.(`[ERROR] [Generate] STATUS=FAILED | durationMs=${Date.now() - startedAt}`, error);
+    throw error;
   }
-
-  const startTime = Date.now();
-  await generateCode(rootPath, { outputPath, configPath });
-  return { durationMs: Date.now() - startTime };
 }
 
-function patchFlowStepsValidationSchema() {
-  const flowStepsSchema = basicValidatorSchema.basicFlowSchema?.properties?.flowSteps;
-  if (!flowStepsSchema || flowStepsSchema.oneOf || !flowStepsSchema.items) {
-    return;
-  }
-
-  const objectStepSchema = {
-    ...flowStepsSchema.items,
-    required: (flowStepsSchema.items.required || []).filter(
-      item => item !== 'stepName'
-    )
-  };
-
-  basicValidatorSchema.basicFlowSchema.properties.flowSteps = {
-    oneOf: [
-      flowStepsSchema,
-      {
-        type: 'object',
-        minProperties: 1,
-        patternProperties: {
-          [basicValidatorSchema.strNotEmptyRegex]: objectStepSchema
-        }
-      }
-    ]
-  };
+async function emitGroups({ project, objects, relationships, flows }) {
+  const [crud, relationship, rbac, system, resource] = await Promise.all([
+    emitCrudApplicationArtifacts({ objects, flows, serviceTag: project.serviceTag }),
+    emitRelationshipApplicationArtifacts({ relationships, flows, serviceTag: project.serviceTag }),
+    emitRbacApplicationArtifacts(objects),
+    emitSystemWebSocketArtifacts(flows, { includeRelationshipOwnTopic: relationships.length > 0 }),
+    emitResourceArtifacts({ objects, relationships, flows })
+  ]);
+  const custom = await emitCustomFlowApplicationArtifacts(flows, { systemFunctions: system.functions, objects });
+  return [
+    { scope: 'crud-flow-schemas', managedPaths: dynamicCrudFlowSchemaPaths, artifacts: emitDynamicCrudFlowSchemas({ objects, flows }) },
+    { scope: 'relationship-flow-schemas', managedPaths: dynamicRelationshipFlowSchemaPaths, artifacts: emitDynamicRelationshipFlowSchemas() },
+    { scope: 'rbac-flow-schemas', managedPaths: rbacFlowSchemaManagedPaths(objects), artifacts: await emitDynamicRbacFlowSchemas({ objects, serviceTag: project.serviceTag }) },
+    { scope: 'crud-application', managedPaths: crudApplicationManagedPaths(), artifacts: crud },
+    { scope: 'relationship-application', managedPaths: relationshipApplicationManagedPaths(), artifacts: relationship },
+    { scope: 'rbac-application', managedPaths: rbacApplicationManagedPaths(objects), artifacts: rbac },
+    { scope: 'system-websocket', managedPaths: systemWebSocketManagedPaths(), artifacts: system.artifacts },
+    { scope: 'custom-flow-application', managedPaths: customFlowApplicationManagedPaths(flows, { includeYaml: hasSystemWebSocket(flows, { includeRelationshipOwnTopic: relationships.length > 0 }) }), artifacts: custom },
+    { scope: 'shared-resources', managedPaths: resourceArtifactPaths, artifacts: resource }
+  ];
 }
-
-function createSilentLogger() {
-  return {
-    debug: () => {},
-    info: () => {},
-    warn: () => {},
-    error: () => {}
-  };
-}
-
-export { generate };

package/src/output/commitArtifacts.js

@@ -0,0 +1,213 @@
+import { constants } from 'node:fs';
+import { copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+import { normalizeArtifactPaths, validateArtifacts } from './validateArtifacts.js';
+import { mergeHooks } from './mergeHooks.js';
+
+const MANAGED_ARTIFACTS_PATH = '.generate-service-code-v2-managed.json';
+const STAGING_PREFIX = '.generate-service-code-v2-stage-';
+
+export async function commitArtifacts(plan) {
+  if (!plan?.project?.outputPath || !Array.isArray(plan.artifacts)) {
+    throw new TypeError('GenerationPlan must include project.outputPath and artifacts');
+  }
+
+  const outputRoot = resolve(plan.project.outputPath);
+  const artifacts = validateArtifacts(plan.artifacts);
+  await mkdir(outputRoot, { recursive: true });
+  const physicalOutputRoot = await realpath(outputRoot);
+  const manifestPath = await resolveSafeTarget(physicalOutputRoot, MANAGED_ARTIFACTS_PATH);
+  const managedArtifacts = await loadManagedArtifacts(manifestPath);
+  const managedScopes = normalizeManagedScopes(plan);
+  const stalePaths = staleManagedPaths(managedScopes, managedArtifacts, artifacts);
+  const mergedArtifacts = await mergeHooks(physicalOutputRoot, artifacts);
+  const stagedRoot = await mkdtemp(join(physicalOutputRoot, STAGING_PREFIX));
+
+  try {
+    const changes = await stageChanges({
+      outputRoot: physicalOutputRoot,
+      stagedRoot,
+      artifacts: mergedArtifacts,
+      stalePaths,
+      manifestPath,
+      manifestContent: managedScopes
+        ? managedManifestContent(managedScopes, managedArtifacts, mergedArtifacts)
+        : undefined
+    });
+    const snapshots = await snapshotChanges(changes, stagedRoot);
+    try {
+      await applyChanges(changes);
+    } catch (error) {
+      await rollbackChanges(changes, snapshots);
+      throw error;
+    }
+  } finally {
+    await rm(stagedRoot, { recursive: true, force: true });
+  }
+
+  return mergedArtifacts.map(({ path }) => ({ path }));
+}
+
+function normalizeManagedScopes(plan) {
+  if (plan.managedScopes !== undefined) {
+    return plan.managedScopes;
+  }
+  if (plan.managedScope === undefined) {
+    return undefined;
+  }
+  return { [plan.managedScope]: normalizeArtifactPaths(plan.managedPaths ?? []) };
+}
+
+function staleManagedPaths(managedScopes, managedArtifacts, artifacts) {
+  if (!managedScopes) {
+    return [];
+  }
+  const emittedPaths = new Set(artifacts.map(artifact => artifact.path));
+  const stalePaths = new Set();
+  for (const [scope, declaredPaths] of Object.entries(managedScopes)) {
+    if (!Object.hasOwn(managedArtifacts, scope)) {
+      continue;
+    }
+    for (const path of [...declaredPaths, ...managedArtifacts[scope]]) {
+      if (!emittedPaths.has(path)) {
+        stalePaths.add(path);
+      }
+    }
+  }
+  return [...stalePaths];
+}
+
+function managedManifestContent(managedScopes, managedArtifacts, artifacts) {
+  const emittedPaths = new Set(artifacts.map(artifact => artifact.path));
+  const nextManifest = { ...managedArtifacts };
+  for (const [scope, paths] of Object.entries(managedScopes)) {
+    nextManifest[scope] = paths.filter(path => emittedPaths.has(path));
+  }
+  return `${JSON.stringify(nextManifest, null, 2)}\n`;
+}
+
+async function stageChanges({ outputRoot, stagedRoot, artifacts, stalePaths, manifestPath, manifestContent }) {
+  const changes = [];
+  for (const artifact of artifacts) {
+    const targetPath = await resolveSafeTarget(outputRoot, artifact.path);
+    const stagedPath = await resolveSafeTarget(stagedRoot, artifact.path, { createDirectories: true });
+    await writeFile(stagedPath, artifact.content, { encoding: 'utf8', flag: constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW });
+    changes.push({ targetPath, stagedPath });
+  }
+  for (const path of stalePaths) {
+    changes.push({ targetPath: await resolveSafeTarget(outputRoot, path), delete: true });
+  }
+  if (manifestContent !== undefined) {
+    const stagedPath = await resolveSafeTarget(stagedRoot, MANAGED_ARTIFACTS_PATH, { createDirectories: true });
+    await writeFile(stagedPath, manifestContent, 'utf8');
+    changes.push({ targetPath: manifestPath, stagedPath });
+  }
+  return changes;
+}
+
+async function snapshotChanges(changes, stagedRoot) {
+  const snapshots = new Map();
+  for (const [index, change] of changes.entries()) {
+    try {
+      const details = await lstat(change.targetPath);
+      if (!details.isFile()) {
+        throw new Error(`Artifact target is not a file: ${change.targetPath}`);
+      }
+      const backupPath = join(stagedRoot, `backup-${index}`);
+      await copyFile(change.targetPath, backupPath, constants.COPYFILE_EXCL);
+      snapshots.set(change.targetPath, { backupPath });
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        snapshots.set(change.targetPath, null);
+        continue;
+      }
+      throw error;
+    }
+  }
+  return snapshots;
+}
+
+async function applyChanges(changes) {
+  for (const change of changes) {
+    if (change.delete) {
+      await unlink(change.targetPath).catch(ignoreMissingFile);
+      continue;
+    }
+    await mkdir(dirname(change.targetPath), { recursive: true });
+    await rename(change.stagedPath, change.targetPath);
+  }
+}
+
+async function rollbackChanges(changes, snapshots) {
+  for (const change of [...changes].reverse()) {
+    const snapshot = snapshots.get(change.targetPath);
+    if (!snapshot) {
+      await unlink(change.targetPath).catch(ignoreMissingFile);
+      continue;
+    }
+    await mkdir(dirname(change.targetPath), { recursive: true });
+    await copyFile(snapshot.backupPath, change.targetPath);
+  }
+}
+
+function ignoreMissingFile(error) {
+  if (error.code !== 'ENOENT') {
+    throw error;
+  }
+}
+
+async function loadManagedArtifacts(manifestPath) {
+  try {
+    const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+      throw new TypeError('Managed artifact manifest must be an object');
+    }
+    for (const paths of Object.values(parsed)) {
+      normalizeArtifactPaths(paths);
+    }
+    return parsed;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+}
+
+async function resolveSafeTarget(outputRoot, artifactPath, { createDirectories = false } = {}) {
+  const targetPath = resolve(outputRoot, artifactPath);
+  if (relative(outputRoot, targetPath).startsWith('..')) {
+    throw new Error(`Artifact path escapes output root: ${artifactPath}`);
+  }
+
+  let currentPath = outputRoot;
+  for (const segment of dirname(artifactPath).split(sep).filter(Boolean)) {
+    currentPath = join(currentPath, segment);
+    try {
+      const details = await lstat(currentPath);
+      if (details.isSymbolicLink() || !details.isDirectory()) {
+        throw new Error(`Artifact path traverses a non-directory: ${artifactPath}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      if (!createDirectories) {
+        break;
+      }
+      await mkdir(currentPath, { recursive: true });
+    }
+  }
+
+  try {
+    if ((await lstat(targetPath)).isSymbolicLink()) {
+      throw new Error(`Artifact path targets a symlink: ${artifactPath}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+  return targetPath;
+}

package/src/output/mergeHooks.js

@@ -0,0 +1,55 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+
+export async function mergeHooks(outputRoot, artifacts) {
+  return Promise.all(artifacts.map(async artifact => ({
+    ...artifact,
+    content: await mergeHook(outputRoot, artifact)
+  })));
+}
+
+async function mergeHook(outputRoot, artifact) {
+  const parts = artifact.path.split(sep);
+  const sourceIndex = parts.lastIndexOf('source');
+  if (sourceIndex < 0 || sourceIndex === parts.length - 1) {
+    return artifact.content;
+  }
+
+  const hookPath = join(outputRoot, ...parts.slice(0, sourceIndex), 'hook', ...parts.slice(sourceIndex + 1));
+  try {
+    if (!(await lstat(hookPath)).isFile()) {
+      return artifact.content;
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return artifact.content;
+    }
+    throw error;
+  }
+
+  const matchers = hookMatchers(artifact.path);
+  if (!matchers) {
+    return artifact.content;
+  }
+
+  const hookContent = await readFile(hookPath, 'utf8');
+  return artifact.content.replace(matchers.anyTag, (match, tagName) => (
+    hookContent.match(matchers.tagPattern(tagName))?.[0] ?? match
+  ));
+}
+
+function hookMatchers(filePath) {
+  if (filePath.endsWith('.js')) {
+    return {
+      anyTag: /\/\/\(<(\w+)>\)([\s\S]*?)\/\/\(<\/\1>\)/gm,
+      tagPattern: name => new RegExp(`\\/\\/\\(<${name}>\\)([\\s\\S]*?)\\/\\/\\(<\\/${name}>\\)`, 'gm')
+    };
+  }
+  if (filePath.endsWith('.yml') || filePath.endsWith('.yaml')) {
+    return {
+      anyTag: /#<#(\w+)#>([\s\S]*?)#<#\/\1#>/gm,
+      tagPattern: name => new RegExp(`#<#${name}#>([\\s\\S]*?)#<#\\/${name}#>`, 'gm')
+    };
+  }
+  return null;
+}

package/src/output/validateArtifacts.js

@@ -0,0 +1,62 @@
+import { isAbsolute, normalize } from 'node:path';
+
+export function normalizeArtifacts(artifacts) {
+  if (!Array.isArray(artifacts)) {
+    throw new TypeError('artifacts must be an array');
+  }
+
+  const paths = new Set();
+  return Object.freeze(artifacts.map(artifact => {
+    if (!artifact || typeof artifact.path !== 'string' || artifact.path.trim() === '') {
+      throw new TypeError('Artifact.path must be a non-empty relative path');
+    }
+    if (isAbsolute(artifact.path)) {
+      throw new TypeError(`Artifact.path must be relative: ${artifact.path}`);
+    }
+    if (typeof artifact.content !== 'string') {
+      throw new TypeError(`Artifact.content must be a string: ${artifact.path}`);
+    }
+
+    const path = normalizeArtifactPath(artifact.path);
+    if (paths.has(path)) {
+      throw new Error(`Duplicate artifact path: ${path}`);
+    }
+    paths.add(path);
+    return Object.freeze({ path, content: artifact.content });
+  }));
+}
+
+export function validateArtifacts(artifacts) {
+  return normalizeArtifacts(artifacts);
+}
+
+export function normalizeArtifactPaths(paths) {
+  if (!Array.isArray(paths)) {
+    throw new TypeError('managedPaths must be an array');
+  }
+
+  const seenPaths = new Set();
+  return Object.freeze(paths.map(path => {
+    const normalizedPath = normalizeArtifactPath(path);
+    if (seenPaths.has(normalizedPath)) {
+      throw new Error(`Duplicate artifact path: ${normalizedPath}`);
+    }
+    seenPaths.add(normalizedPath);
+    return normalizedPath;
+  }));
+}
+
+function normalizeArtifactPath(path) {
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw new TypeError('Artifact.path must be a non-empty relative path');
+  }
+  if (isAbsolute(path)) {
+    throw new TypeError(`Artifact.path must be relative: ${path}`);
+  }
+
+  const normalizedPath = normalize(path);
+  if (normalizedPath === '..' || normalizedPath.startsWith('../')) {
+    throw new TypeError(`Artifact.path escapes output root: ${path}`);
+  }
+  return normalizedPath;
+}

package/src/plan/buildGenerationPlan.js

@@ -0,0 +1,50 @@
+import { normalizeArtifactPaths, validateArtifacts } from '../output/validateArtifacts.js';
+
+export function buildGenerationPlan(project, artifacts = [], { managedPaths = [], managedScope, managedScopes } = {}) {
+  if (!project?.rootPath || !project?.outputPath) {
+    throw new TypeError('ProjectModel must include rootPath and outputPath');
+  }
+  if (managedScope !== undefined && managedScopes !== undefined) {
+    throw new TypeError('GenerationPlan must use managedScope or managedScopes, not both');
+  }
+  return Object.freeze({
+    project,
+    artifacts: validateArtifacts(artifacts),
+    managedPaths: normalizeArtifactPaths(managedPaths),
+    managedScope: normalizeManagedScope(managedScope),
+    managedScopes: normalizeManagedScopes(managedScopes)
+  });
+}
+
+function normalizeManagedScope(scope) {
+  if (scope === undefined) {
+    return undefined;
+  }
+  if (typeof scope !== 'string' || scope.trim() === '') {
+    throw new TypeError('managedScope must be a non-empty string');
+  }
+  return scope;
+}
+
+function normalizeManagedScopes(scopes) {
+  if (scopes === undefined) {
+    return undefined;
+  }
+  if (!scopes || Array.isArray(scopes) || typeof scopes !== 'object') {
+    throw new TypeError('managedScopes must be an object of scope paths');
+  }
+  const seenPaths = new Set();
+  const normalized = {};
+  for (const [scope, paths] of Object.entries(scopes)) {
+    const scopeName = normalizeManagedScope(scope);
+    const normalizedPaths = normalizeArtifactPaths(paths);
+    for (const path of normalizedPaths) {
+      if (seenPaths.has(path)) {
+        throw new Error(`Artifact path belongs to multiple managed scopes: ${path}`);
+      }
+      seenPaths.add(path);
+    }
+    normalized[scopeName] = normalizedPaths;
+  }
+  return Object.freeze(normalized);
+}