add --allow-unsupported flag for pipeline conversion

Allow pipeline conversion to continue when encountering unsupported
pipelets by generating TODO comments instead of failing. This enables
partial conversion of pipelines that contain pipelets without script
API equivalents (e.g., GetLastVisitedProducts, ImportInventoryLists).

- Add --allow-unsupported CLI flag
- Modify validatePipeline() to return warnings instead of throwing
- Generate UNSUPPORTED comments with reason and key bindings
- Add tests for the new functionality

Author: clavery

packages/b2c-cli/src/commands/pipeline/convert.ts

@@ -59,6 +59,10 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
       description: 'Preview generated code without writing files',
       default: false,
     }),
+    'allow-unsupported': Flags.boolean({
+      description: 'Continue conversion with unsupported pipelets (generates TODO comments instead of failing)',
+      default: false,
+    }),
   };
 
   protected operations = {
@@ -67,7 +71,7 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
 
   async run(): Promise<ConvertResponse> {
     const {input} = this.args;
-    const {output, 'dry-run': dryRun} = this.flags;
+    const {output, 'dry-run': dryRun, 'allow-unsupported': allowUnsupported} = this.flags;
 
     // Resolve input files
     const inputFiles = await this.resolveInputFiles(input);
@@ -81,7 +85,7 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
     }
 
     // Process all files and collect results
-    const conversionResults = await this.processFiles(inputFiles, output, dryRun);
+    const conversionResults = await this.processFiles(inputFiles, output, dryRun, allowUnsupported);
 
     const response: ConvertResponse = {
       results: conversionResults.results,
@@ -130,6 +134,7 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
     inputFile: string,
     output: string | undefined,
     dryRun: boolean,
+    allowUnsupported: boolean,
   ): Promise<{result?: ConvertResult; success: boolean; error?: ConvertError}> {
     const pipelineName = basename(inputFile, '.xml');
 
@@ -152,6 +157,7 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
       const result = await this.operations.convertPipeline(inputFile, {
         outputPath,
         dryRun,
+        allowUnsupported,
       });
 
       if (result.warnings.length > 0) {
@@ -181,8 +187,8 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
       }
 
       return {result, success};
-    } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : String(err);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
       this.logToStderr(
         t('commands.pipeline.convert.failed', 'Failed to convert {{name}}: {{error}}', {
           name: pipelineName,
@@ -203,6 +209,7 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
     inputFiles: string[],
     output: string | undefined,
     dryRun: boolean,
+    allowUnsupported: boolean,
   ): Promise<{
     results: ConvertResult[];
     errors: ConvertError[];
@@ -219,7 +226,7 @@ export default class PipelineConvert extends BaseCommand<typeof PipelineConvert>
     // Process files sequentially to maintain order and avoid concurrent file operations
     for (const inputFile of inputFiles) {
       // eslint-disable-next-line no-await-in-loop
-      const fileResult = await this.processFile(inputFile, output, dryRun);
+      const fileResult = await this.processFile(inputFile, output, dryRun, allowUnsupported);
       if (fileResult.result) {
         results.push(fileResult.result);
         warningCount += fileResult.result.warnings.length;

packages/b2c-tooling-sdk/src/operations/pipeline/generator/helpers.ts

@@ -23,6 +23,14 @@ export const VARIABLE_MAPPINGS: Record<string, string> = {
   CurrentHttpParameterMap: 'request.httpParameterMap',
 };
 
+/**
+ * Options for code generation.
+ */
+export interface GeneratorOptions {
+  /** If true, allow unsupported pipelets to be converted with UNSUPPORTED comments instead of failing. */
+  allowUnsupported?: boolean;
+}
+
 /**
  * Context for code generation.
  */
@@ -37,6 +45,8 @@ export interface GeneratorContext {
   requires: Map<string, string>;
   /** The current pipeline name (for call node resolution). */
   pipelineName: string;
+  /** Generator options. */
+  options?: GeneratorOptions;
 }
 
 /**

packages/b2c-tooling-sdk/src/operations/pipeline/generator/index.ts

@@ -14,16 +14,17 @@
 
 import type {AnalyzedFunction, AnalysisResult, PipelineIR} from '../types.js';
 import {generateBlock} from './blocks.js';
-import {type GeneratorContext, getRequireVarName, indent} from './helpers.js';
+import {type GeneratorContext, type GeneratorOptions, getRequireVarName, indent} from './helpers.js';
 
 /**
  * Generates JavaScript controller code from the analysis result.
  *
  * @param pipeline - The parsed pipeline IR
  * @param analysis - The control flow analysis result
+ * @param options - Generator options
  * @returns Generated JavaScript code
  */
-export function generateController(pipeline: PipelineIR, analysis: AnalysisResult): string {
+export function generateController(pipeline: PipelineIR, analysis: AnalysisResult, options?: GeneratorOptions): string {
   // Collect all requires from all functions
   // Only include dw/* modules and relative controller paths at the top
   // Script pipelets use inline require() calls
@@ -54,6 +55,7 @@ export function generateController(pipeline: PipelineIR, analysis: AnalysisResul
       declaredVars: new Set(),
       requires: allRequires,
       pipelineName: pipeline.name,
+      options,
     };
 
     const funcCode = generateFunction(func, context);

packages/b2c-tooling-sdk/src/operations/pipeline/generator/nodes.ts

@@ -10,6 +10,7 @@
  * @module operations/pipeline/generator/nodes
  */
 
+import {getUnconvertablePipelet} from '../pipelets/index.js';
 import type {
   CallNodeIR,
   EndNodeIR,
@@ -250,6 +251,20 @@ function generatePipeletNode(node: PipeletNodeIR, context: GeneratorContext): st
   const ind = indent(context.indent);
   const lines: string[] = [];
 
+  // Check if pipelet is unconvertable (only when allowUnsupported is true)
+  if (context.options?.allowUnsupported) {
+    const unconvertableInfo = getUnconvertablePipelet(node.pipeletName);
+    if (unconvertableInfo) {
+      lines.push(`${ind}// UNSUPPORTED: ${node.pipeletName}`);
+      lines.push(`${ind}// Reason: ${unconvertableInfo.unconvertableReason ?? 'No script API equivalent'}`);
+      lines.push(`${ind}// TODO: Manual conversion required`);
+      for (const kb of node.keyBindings) {
+        lines.push(`${ind}//   ${kb.key} = ${kb.value}`);
+      }
+      return lines.join('\n');
+    }
+  }
+
   switch (node.pipeletName) {
     // Common pipelets
     case 'Assign':

packages/b2c-tooling-sdk/src/operations/pipeline/index.ts

@@ -73,9 +73,12 @@ export class UnconvertablePipelineError extends Error {
 
 /**
  * Validates a pipeline for unconvertable pipelets.
- * @throws UnconvertablePipelineError if any unconvertable pipelets are found
+ * @param pipeline - The pipeline IR to validate
+ * @param allowUnsupported - If true, return warnings instead of throwing
+ * @returns Array of warning messages when allowUnsupported is true
+ * @throws UnconvertablePipelineError if unconvertable pipelets are found and allowUnsupported is false
  */
-function validatePipeline(pipeline: PipelineIR): void {
+function validatePipeline(pipeline: PipelineIR, allowUnsupported: boolean = false): string[] {
   const unconvertable: Array<{name: string; reason: string}> = [];
 
   for (const node of pipeline.nodes.values()) {
@@ -95,8 +98,14 @@ function validatePipeline(pipeline: PipelineIR): void {
   }
 
   if (unconvertable.length > 0) {
+    if (allowUnsupported) {
+      // Return warnings instead of throwing
+      return unconvertable.map((p) => `Unsupported pipelet "${p.name}": ${p.reason}`);
+    }
     throw new UnconvertablePipelineError(pipeline.name, unconvertable);
   }
+
+  return [];
 }
 
 // Re-export all types
@@ -173,13 +182,13 @@ export async function convertPipeline(inputPath: string, options: ConvertOptions
   const pipeline = await parsePipeline(xml, pipelineName);
 
   // Validate for unconvertable pipelets
-  validatePipeline(pipeline);
+  const validationWarnings = validatePipeline(pipeline, options.allowUnsupported);
 
   // Analyze
   const analysis = analyzePipeline(pipeline);
 
-  // Generate
-  const code = generateController(pipeline, analysis);
+  // Generate (pass allowUnsupported to enable UNSUPPORTED comment generation)
+  const code = generateController(pipeline, analysis, {allowUnsupported: options.allowUnsupported});
 
   // Write output if not dry-run
   let outputPath: string | undefined;
@@ -192,7 +201,7 @@ export async function convertPipeline(inputPath: string, options: ConvertOptions
     pipelineName,
     code,
     outputPath,
-    warnings: analysis.warnings,
+    warnings: [...validationWarnings, ...analysis.warnings],
   };
 }
 
@@ -212,15 +221,19 @@ export async function convertPipeline(inputPath: string, options: ConvertOptions
  * console.log(result.code);
  * ```
  */
-export async function convertPipelineContent(xml: string, pipelineName: string): Promise<ConvertResult> {
+export async function convertPipelineContent(
+  xml: string,
+  pipelineName: string,
+  options: ConvertOptions = {},
+): Promise<ConvertResult> {
   const pipeline = await parsePipeline(xml, pipelineName);
-  validatePipeline(pipeline);
+  const validationWarnings = validatePipeline(pipeline, options.allowUnsupported);
   const analysis = analyzePipeline(pipeline);
-  const code = generateController(pipeline, analysis);
+  const code = generateController(pipeline, analysis, {allowUnsupported: options.allowUnsupported});
 
   return {
     pipelineName,
     code,
-    warnings: analysis.warnings,
+    warnings: [...validationWarnings, ...analysis.warnings],
   };
 }

packages/b2c-tooling-sdk/src/operations/pipeline/types.ts

@@ -27,6 +27,8 @@ export interface ConvertOptions {
   outputPath?: string;
   /** If true, don't write the file, just return the generated code. */
   dryRun?: boolean;
+  /** If true, allow unsupported pipelets to be converted with TODO comments instead of failing. */
+  allowUnsupported?: boolean;
 }
 
 /**

packages/b2c-tooling-sdk/test/operations/pipeline/generator.test.ts

@@ -10,6 +10,7 @@ import {
   analyzePipeline,
   generateController,
   convertPipelineContent,
+  UnconvertablePipelineError,
 } from '@salesforce/b2c-tooling-sdk/operations/pipeline';
 
 describe('operations/pipeline/generator', () => {
@@ -780,4 +781,61 @@ describe('operations/pipeline/generator', () => {
       expect(result.code).to.include('exports.Edit.public = true;');
     });
   });
+
+  describe('allowUnsupported option', () => {
+    const xmlWithUnconvertable = `<?xml version="1.0" encoding="UTF-8"?>
+      <pipeline>
+        <branch basename="Test">
+          <segment>
+            <node><start-node name="Test"/></node>
+            <simple-transition/>
+            <node>
+              <pipelet-node pipelet-name="GetLastVisitedProducts" pipelet-set-identifier="bc_api">
+                <key-binding alias="Products" key="Products"/>
+              </pipelet-node>
+            </node>
+            <simple-transition/>
+            <node><end-node/></node>
+          </segment>
+        </branch>
+      </pipeline>`;
+
+    it('throws UnconvertablePipelineError by default for unsupported pipelets', async () => {
+      try {
+        await convertPipelineContent(xmlWithUnconvertable, 'Test');
+        expect.fail('Should have thrown UnconvertablePipelineError');
+      } catch (error) {
+        expect(error).to.be.instanceOf(UnconvertablePipelineError);
+        expect((error as UnconvertablePipelineError).pipelineName).to.equal('Test');
+        expect((error as UnconvertablePipelineError).unconvertablePipelets).to.have.length(1);
+        expect((error as UnconvertablePipelineError).unconvertablePipelets[0].name).to.equal('GetLastVisitedProducts');
+      }
+    });
+
+    it('generates UNSUPPORTED comments when allowUnsupported is true', async () => {
+      const result = await convertPipelineContent(xmlWithUnconvertable, 'Test', {allowUnsupported: true});
+
+      expect(result.code).to.include('// UNSUPPORTED: GetLastVisitedProducts');
+      expect(result.code).to.include('// Reason: Session-based pipelet');
+      expect(result.code).to.include('// TODO: Manual conversion required');
+      expect(result.code).to.include('//   Products = Products');
+    });
+
+    it('returns warnings for unsupported pipelets when allowUnsupported is true', async () => {
+      const result = await convertPipelineContent(xmlWithUnconvertable, 'Test', {allowUnsupported: true});
+
+      expect(result.warnings).to.include(
+        'Unsupported pipelet "GetLastVisitedProducts": Session-based pipelet. Use session.custom or clickstream API instead.',
+      );
+    });
+
+    it('works with generateController directly when allowUnsupported is true', async () => {
+      const pipeline = await parsePipeline(xmlWithUnconvertable, 'Test');
+      const analysis = analyzePipeline(pipeline);
+      const code = generateController(pipeline, analysis, {allowUnsupported: true});
+
+      expect(code).to.include('// UNSUPPORTED: GetLastVisitedProducts');
+      expect(code).to.include('// TODO: Manual conversion required');
+    });
+  });
 });