@contentful/experience-design-system-cli 2.7.5-dev-build-752dc9c.0 → 2.10.1-dev-build-90df010.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.7.5-dev-build-752dc9c.0",
+  "version": "2.10.1-dev-build-90df010.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/build-analyze-view-rows.d.ts

@@ -0,0 +1,23 @@
+import type { RawComponentDefinition } from '../types.js';
+import type { AnalyzeViewResult } from './tui/AnalyzeView.js';
+type AnalyzeViewRow = AnalyzeViewResult['components'][number];
+/**
+ * Build the per-component rows shown in the analyze TUI / non-TTY summary,
+ * pairing each filtered component with its corresponding validation result.
+ *
+ * IMPORTANT — positional indexing is intentional and load-bearing.
+ * `validateExtractedComponents` is implemented as `.map()` over its input,
+ * so `validatedComponents[i]` always corresponds to `filteredComponents[i]`.
+ *
+ * We previously keyed validated components by `name` to "avoid a positional
+ * dependency" — that got the tradeoff exactly backwards. `Map.set` overwrites
+ * by key, so for two components named "Button" only the second's
+ * `validationIssues` survived in the Map. The first row's errors then
+ * disappeared from `analyzeResult` entirely: no Errors-section entry, no
+ * row badge, no count. Pairing by index restores correctness.
+ */
+export declare function buildAnalyzeViewRows(filteredComponents: RawComponentDefinition[], validatedComponents: RawComponentDefinition[], allWarnings: string[]): {
+    rows: AnalyzeViewRow[];
+    totalErrors: number;
+};
+export {};

package/dist/src/analyze/build-analyze-view-rows.js

@@ -0,0 +1,39 @@
+/**
+ * Build the per-component rows shown in the analyze TUI / non-TTY summary,
+ * pairing each filtered component with its corresponding validation result.
+ *
+ * IMPORTANT — positional indexing is intentional and load-bearing.
+ * `validateExtractedComponents` is implemented as `.map()` over its input,
+ * so `validatedComponents[i]` always corresponds to `filteredComponents[i]`.
+ *
+ * We previously keyed validated components by `name` to "avoid a positional
+ * dependency" — that got the tradeoff exactly backwards. `Map.set` overwrites
+ * by key, so for two components named "Button" only the second's
+ * `validationIssues` survived in the Map. The first row's errors then
+ * disappeared from `analyzeResult` entirely: no Errors-section entry, no
+ * row badge, no count. Pairing by index restores correctness.
+ */
+export function buildAnalyzeViewRows(filteredComponents, validatedComponents, allWarnings) {
+    if (validatedComponents.length !== filteredComponents.length) {
+        // Defensive: caller must pass aligned arrays. If this ever fires we want
+        // to know loudly rather than silently mis-pair rows with their issues.
+        throw new Error(`buildAnalyzeViewRows: validatedComponents length (${validatedComponents.length}) does not match filteredComponents length (${filteredComponents.length})`);
+    }
+    let totalErrors = 0;
+    const rows = filteredComponents.map((c, i) => {
+        const validated = validatedComponents[i];
+        const errorIssues = (validated.validationIssues ?? []).filter((issue) => issue.severity === 'error');
+        totalErrors += errorIssues.length;
+        return {
+            name: c.name,
+            framework: c.framework,
+            propCount: c.props.length,
+            slotCount: c.slots.length,
+            warnings: allWarnings.filter((w) => w.startsWith(c.name + ':')),
+            errors: errorIssues.map((issue) => issue.message),
+            extractionConfidence: c.extractionConfidence ?? null,
+            needsReview: c.needsReview ?? false,
+        };
+    });
+    return { rows, totalErrors };
+}

package/dist/src/analyze/command.js

@@ -12,6 +12,7 @@ import { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
 import { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
 import { describeReviewReasons, inspectComponentSource } from './extract/source-inspection.js';
 import { validateExtractedComponents } from './extract/validate.js';
+import { buildAnalyzeViewRows } from './build-analyze-view-rows.js';
 const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.ts', '.tsx', '.vue']);
 const IGNORED_DIRECTORY_NAMES = new Set([
     '.git',
@@ -175,20 +176,14 @@ export function registerAnalyzeCommand(program) {
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();
         const allWarnings = [...extraction.warnings, ...filterWarnings];
+        const { rows: componentRows, totalErrors } = buildAnalyzeViewRows(filteredComponents, validatedComponents, allWarnings);
         const analyzeResult = {
             sourceDirectory,
             sessionId,
             fileCount: sourceFiles.length,
-            components: filteredComponents.map((c) => ({
-                name: c.name,
-                framework: c.framework,
-                propCount: c.props.length,
-                slotCount: c.slots.length,
-                warnings: allWarnings.filter((w) => w.startsWith(c.name + ':')),
-                extractionConfidence: c.extractionConfidence ?? null,
-                needsReview: c.needsReview ?? false,
-            })),
+            components: componentRows,
             totalWarnings: allWarnings.length,
+            totalErrors,
         };
         if (process.stdout.isTTY) {
             const { waitUntilExit } = render(createElement(AnalyzeView, {
@@ -204,11 +199,19 @@ export function registerAnalyzeCommand(program) {
                 `Scanned ${pluralize(sourceFiles.length, 'source file')} in ${sourceDirectory}`,
                 `Extracted ${pluralize(extraction.components.length, 'component')}`,
             ];
+            if (totalErrors > 0) {
+                summaryLines.push(`Errors (${totalErrors}):`);
+                for (const c of componentRows) {
+                    for (const e of c.errors) {
+                        summaryLines.push(`- ${c.name}: ${e}`);
+                    }
+                }
+            }
             if (allWarnings.length > 0) {
                 summaryLines.push(`Warnings (${allWarnings.length}):`);
                 summaryLines.push(...allWarnings.map((w) => `- ${w}`));
             }
-            else {
+            else if (totalErrors === 0) {
                 summaryLines.push('Warnings: none');
             }
             process.stderr.write(summaryLines.join('\n') + '\n');

package/dist/src/analyze/extract/validate.d.ts

@@ -1,4 +1,16 @@
-import type { RawComponentDefinition } from '../../types.js';
+import type { RawComponentDefinition, ExtractionValidationIssue } from '../../types.js';
 export type { ExtractionValidationIssue } from '../../types.js';
 export declare function validateExtractedComponents(components: RawComponentDefinition[]): RawComponentDefinition[];
 export declare function shouldExcludeDueToValidation(component: RawComponentDefinition): boolean;
+/**
+ * Format a stderr-ready warning describing components auto-rejected by the
+ * extraction gate. Used by `analyze select --select-all --exclude-invalid`
+ * and `analyze select-agent --exclude-invalid` so both opt-in paths emit a
+ * consistent message — non-interactive callers (CI, orchestrator, scripted
+ * pipeline) need to see WHICH components were excluded and WHY, not just
+ * the bare counts.
+ */
+export declare function formatExclusionWarning(rejected: Array<{
+    name: string;
+    validationIssues?: ExtractionValidationIssue[];
+}>): string;

package/dist/src/analyze/extract/validate.js

@@ -25,21 +25,27 @@ export function validateExtractedComponents(components) {
         }
         for (let i = 0; i < component.slots.length; i++) {
             if (!component.slots[i].name.trim()) {
+                // Warning, not error: SP-2's renameEmptySlots auto-recovers empty slot
+                // names to children/slot_<n> before the LLM prompt, so the component
+                // can still be generated. Asymmetric with EMPTY_PROP_NAME (still error)
+                // because that path silently drops empty-named props in
+                // loadCDFComponents — real data loss — instead of recovering them.
                 issues.push({
-                    severity: 'error',
+                    severity: 'warning',
                     code: 'EMPTY_SLOT_NAME',
                     message: `Slot at index ${i} has an empty name`,
                     field: `slots[${i}].name`,
                 });
             }
         }
-        const propNames = new Set(component.props.map((p) => p.name));
+        const propNames = new Set(component.props.map((p) => p.name.trim()).filter(Boolean));
         for (let i = 0; i < component.slots.length; i++) {
-            if (component.slots[i].name && propNames.has(component.slots[i].name)) {
+            const slotName = component.slots[i].name.trim();
+            if (slotName && propNames.has(slotName)) {
                 issues.push({
                     severity: 'error',
                     code: 'PROP_SLOT_NAME_COLLISION',
-                    message: `"${component.slots[i].name}" is used as both a prop name and a slot name`,
+                    message: `"${slotName}" is used as both a prop name and a slot name`,
                     field: `slots[${i}].name`,
                 });
             }
@@ -47,7 +53,7 @@ export function validateExtractedComponents(components) {
         const nameKey = component.name.trim();
         if (nameKey && (nameCounts.get(nameKey) ?? 0) > 1) {
             issues.push({
-                severity: 'warning',
+                severity: 'error',
                 code: 'DUPLICATE_COMPONENT_NAME',
                 message: `Component name "${component.name}" appears more than once in the extracted set`,
             });
@@ -65,3 +71,24 @@ export function validateExtractedComponents(components) {
 export function shouldExcludeDueToValidation(component) {
     return (component.validationIssues ?? []).some((i) => i.severity === 'error');
 }
+/**
+ * Format a stderr-ready warning describing components auto-rejected by the
+ * extraction gate. Used by `analyze select --select-all --exclude-invalid`
+ * and `analyze select-agent --exclude-invalid` so both opt-in paths emit a
+ * consistent message — non-interactive callers (CI, orchestrator, scripted
+ * pipeline) need to see WHICH components were excluded and WHY, not just
+ * the bare counts.
+ */
+export function formatExclusionWarning(rejected) {
+    if (rejected.length === 0)
+        return '';
+    const lines = [`Warning: ${rejected.length} component(s) excluded due to validation errors:`];
+    for (const comp of rejected) {
+        const codes = (comp.validationIssues ?? [])
+            .filter((i) => i.severity === 'error')
+            .map((i) => i.code)
+            .join(', ');
+        lines.push(`  ✗  ${comp.name}  ${codes}`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/src/analyze/select/command.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import type { ReviewSessionSnapshot } from './types.js';
+import type { PreviewValidationError } from '../../apply/api-client.js';
 /**
  * Load components from the pipeline DB and re-run extraction validation.
  *
@@ -9,4 +10,40 @@ import type { ReviewSessionSnapshot } from './types.js';
  * review snapshot — otherwise the TUI sees no validation errors at all.
  */
 export declare function loadAndValidateForReview(sessionId: string, projectRoot: string | undefined): Promise<ReviewSessionSnapshot>;
+/**
+ * Synthesize SERVER_VALIDATION_FAILED issues onto the review state file's
+ * matching components. Used by the wizard's 422 recovery path: after a
+ * preview-API validation error, this runs before re-launching the
+ * analyze-select TUI so the Sidebar's existing red-warning rendering
+ * pins the offenders to the top.
+ *
+ * Idempotent on identical input is NOT a contract: each call appends.
+ * The wizard's 422 path is a one-shot per preview attempt, so duplicate
+ * issues only matter if a caller invokes this twice without the user
+ * round-tripping through the TUI in between.
+ */
+export declare function patchReviewStateWithValidationErrors(sessionId: string, errors: PreviewValidationError[], opts?: {
+    artifactsRoot?: string;
+}): Promise<{
+    patchedNames: string[];
+    missingNames: string[];
+}>;
+/**
+ * Exclude components whose names appear in `names` from the next preview/push.
+ * Used by the wizard's "skip and retry" path after a 422.
+ *
+ * Two stores are updated:
+ *   - Pipeline DB (`raw_components.status` → `'generate-rejected'`) so that
+ *     `loadCDFComponents()` excludes them from the next manifest. This is the
+ *     load-bearing change — preview reads from the DB, not the JSON file.
+ *   - Review state JSON (`status` → `'rejected'`) so that if the user re-enters
+ *     the analyze-select TUI later, the rejected status is reflected.
+ *
+ * `'generate-rejected'` matches the existing convention for "component was
+ * generated successfully but later excluded" (see GenerateReviewStep) — the
+ * component generated fine locally but failed server-side validation.
+ */
+export declare function rejectComponentsByName(sessionId: string, names: string[], opts?: {
+    artifactsRoot?: string;
+}): Promise<void>;
 export declare function registerAnalyzeEditCommand(program: Command): void;

package/dist/src/analyze/select/command.js

@@ -1,12 +1,12 @@
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { access, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
 import { createElement } from 'react';
 import { render } from 'ink';
 import { getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState } from './persistence.js';
 import { loadReviewInput } from './parser.js';
 import { App } from './tui/App.js';
 import { openPipelineDb, loadRawComponents, storeRawComponents, createStep, updateStep } from '../../session/db.js';
-import { validateExtractedComponents, shouldExcludeDueToValidation } from '../extract/validate.js';
+import { validateExtractedComponents, shouldExcludeDueToValidation, formatExclusionWarning, } from '../extract/validate.js';
 const SAFE_PATH_RE = /^[a-zA-Z0-9_.$[\]=]+$/;
 const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function applyDotPath(obj, path, value) {
@@ -73,10 +73,66 @@ function applyPatch(snapshot, ops) {
     return { ...snapshot, components };
 }
 async function runNonInteractive(snapshot, opts, paths, sessionId) {
+    // --exclude-components on its own (no --select-all / --select / --deselect /
+    // --reject / --patch) is the orchestrator's 422 retry-loop invocation: only
+    // the named components should change. The rebuild path below calls
+    // storeRawComponents which DELETEs all rows and re-inserts with default
+    // status='extracted', wiping the post-generate state required by
+    // loadCDFComponents (status='generated' + raw_props.cdf_type populated).
+    // Short-circuit through rejectComponentsByName, which is a pure UPDATE.
+    const onlyExcludeComponents = !!opts.excludeComponents &&
+        !opts.acceptAll &&
+        !opts.selectAll &&
+        !(opts.select ?? []).length &&
+        !(opts.deselect ?? []).length &&
+        !(opts.reject ?? []).length &&
+        !opts.patch;
+    if (onlyExcludeComponents) {
+        const names = opts
+            .excludeComponents.split(',')
+            .map((n) => n.trim())
+            .filter(Boolean);
+        if (names.length > 0) {
+            // paths.sessionDir = resolve(artifactsRoot, sessionId), so dirname gives
+            // back the artifactsRoot — keeps rejectComponentsByName from re-resolving
+            // it via env var when the caller already knows it.
+            const artifactsRoot = dirname(paths.sessionDir);
+            await rejectComponentsByName(sessionId, names, { artifactsRoot });
+        }
+        const accepted = snapshot.components.filter((c) => c.status === 'accepted').length;
+        const rejected = snapshot.components.filter((c) => c.status === 'rejected').length + (names.length || 0);
+        process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}\n`);
+        return;
+    }
     let result = { ...snapshot };
     const rejectPatterns = [...(opts.reject ?? []), ...(opts.deselect ?? [])].map((p) => p.toLowerCase());
     const selectPatterns = (opts.select ?? []).map((p) => p.toLowerCase());
     const selectAll = opts.acceptAll || opts.selectAll;
+    // Fail-loud gate: --select-all stops with a non-zero exit when ANY component
+    // has error-severity validation issues. The user must opt in to auto-rejection
+    // with --exclude-invalid. Silent exclusion in CI / orchestrator contexts is
+    // dangerous — the caller should see and acknowledge that components are
+    // being dropped from the import.
+    if (selectAll && !opts.excludeInvalid) {
+        const invalid = result.components.filter((c) => shouldExcludeDueToValidation(c.originalProposal));
+        if (invalid.length > 0) {
+            const lines = [
+                `Error: ${invalid.length} component(s) failed validation; refusing --select-all without --exclude-invalid:`,
+            ];
+            for (const c of invalid) {
+                const codes = (c.originalProposal.validationIssues ?? [])
+                    .filter((i) => i.severity === 'error')
+                    .map((i) => i.code)
+                    .join(', ');
+                lines.push(`  ✗  ${c.name}  ${codes}`);
+            }
+            lines.push('');
+            lines.push('Re-run with --exclude-invalid to auto-reject these components, or run analyze select interactively to fix them.');
+            process.stderr.write(lines.join('\n') + '\n');
+            process.exit(1);
+            return;
+        }
+    }
     if (selectAll || rejectPatterns.length > 0 || selectPatterns.length > 0) {
         result = {
             ...result,
@@ -95,6 +151,21 @@ async function runNonInteractive(snapshot, opts, paths, sessionId) {
             }),
         };
     }
+    // Apply --exclude-components: force-reject the named components regardless of
+    // how --select-all / --select / --deselect classified them. Used by the
+    // orchestrator's 422 retry loop to exclude server-validation offenders.
+    if (opts.excludeComponents) {
+        const excludeNames = new Set(opts.excludeComponents
+            .split(',')
+            .map((n) => n.trim())
+            .filter(Boolean));
+        if (excludeNames.size > 0) {
+            result = {
+                ...result,
+                components: result.components.map((c) => excludeNames.has(c.name) ? { ...c, status: 'rejected' } : c),
+            };
+        }
+    }
     // Apply --patch
     if (opts.patch) {
         let patchOps;
@@ -124,10 +195,31 @@ async function runNonInteractive(snapshot, opts, paths, sessionId) {
     }
     const accepted = result.components.filter((c) => c.status === 'accepted');
     const rejected = result.components.filter((c) => c.status === 'rejected');
+    // Surface what was excluded by --select-all --exclude-invalid so the
+    // non-interactive caller (CI, orchestrator, scripted pipeline) doesn't
+    // have to guess what failed validation. The warning is printed BEFORE
+    // saveReviewState so the message lands ahead of the bare counts.
+    if (selectAll && opts.excludeInvalid) {
+        const autoRejected = rejected
+            .filter((c) => shouldExcludeDueToValidation(c.originalProposal))
+            .map((c) => ({ name: c.name, validationIssues: c.originalProposal.validationIssues }));
+        process.stderr.write(formatExclusionWarning(autoRejected));
+    }
     // Persist decisions to session state so pipeline orchestrator can read them
     await saveReviewState(paths.statePath, result);
-    // Sync edited proposals back to the DB so generation uses the user's edits
-    if (accepted.length > 0) {
+    // Sync edited proposals back to the DB so generation uses the user's edits.
+    //
+    // Only --patch can mutate editedProposal — the other non-interactive flags
+    // (--select-all / --select / --deselect / --reject / --exclude-invalid)
+    // change status only. Calling storeRawComponents in the no-edit case is
+    // not just wasteful: it's destructive. storeRawComponents starts with
+    // `DELETE FROM raw_components WHERE session_id = ?` and re-inserts only
+    // the components passed in — so on a --select-all run, every rejected
+    // component (including its raw_slots / raw_props children) is physically
+    // removed. A second invocation of the same command would then see a
+    // smaller snapshot, lose the rejected component(s), and report different
+    // counts.
+    if (opts.patch && accepted.length > 0) {
         const db = openPipelineDb();
         try {
             storeRawComponents(db, sessionId, accepted.map((c) => c.editedProposal));
@@ -158,6 +250,100 @@ export async function loadAndValidateForReview(sessionId, projectRoot) {
     const validatedComponents = validateExtractedComponents(rawComponents);
     return loadReviewInput(validatedComponents, { reviewRoot: projectRoot });
 }
+/**
+ * Synthesize SERVER_VALIDATION_FAILED issues onto the review state file's
+ * matching components. Used by the wizard's 422 recovery path: after a
+ * preview-API validation error, this runs before re-launching the
+ * analyze-select TUI so the Sidebar's existing red-warning rendering
+ * pins the offenders to the top.
+ *
+ * Idempotent on identical input is NOT a contract: each call appends.
+ * The wizard's 422 path is a one-shot per preview attempt, so duplicate
+ * issues only matter if a caller invokes this twice without the user
+ * round-tripping through the TUI in between.
+ */
+export async function patchReviewStateWithValidationErrors(sessionId, errors, opts = {}) {
+    const artifactsRoot = opts.artifactsRoot ?? getRefineArtifactsRoot();
+    const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+    let snapshot;
+    try {
+        await access(paths.statePath);
+        snapshot = JSON.parse(await readFile(paths.statePath, 'utf8'));
+    }
+    catch {
+        snapshot = await loadAndValidateForReview(sessionId, undefined);
+        snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);
+    }
+    const errorsByName = new Map();
+    for (const err of errors) {
+        const list = errorsByName.get(err.componentName) ?? [];
+        list.push(err);
+        errorsByName.set(err.componentName, list);
+    }
+    const patchedNames = [];
+    const knownNames = new Set(snapshot.components.map((c) => c.name));
+    const components = snapshot.components.map((c) => {
+        const matched = errorsByName.get(c.name);
+        if (!matched || matched.length === 0)
+            return c;
+        patchedNames.push(c.name);
+        const newIssues = matched.map((err) => ({
+            severity: 'error',
+            code: 'SERVER_VALIDATION_FAILED',
+            message: err.message,
+        }));
+        const existing = c.originalProposal.validationIssues ?? [];
+        return {
+            ...c,
+            originalProposal: {
+                ...c.originalProposal,
+                validationIssues: [...existing, ...newIssues],
+            },
+        };
+    });
+    const missingNames = [...errorsByName.keys()].filter((n) => !knownNames.has(n));
+    await saveReviewState(paths.statePath, { ...snapshot, components });
+    return { patchedNames, missingNames };
+}
+/**
+ * Exclude components whose names appear in `names` from the next preview/push.
+ * Used by the wizard's "skip and retry" path after a 422.
+ *
+ * Two stores are updated:
+ *   - Pipeline DB (`raw_components.status` → `'generate-rejected'`) so that
+ *     `loadCDFComponents()` excludes them from the next manifest. This is the
+ *     load-bearing change — preview reads from the DB, not the JSON file.
+ *   - Review state JSON (`status` → `'rejected'`) so that if the user re-enters
+ *     the analyze-select TUI later, the rejected status is reflected.
+ *
+ * `'generate-rejected'` matches the existing convention for "component was
+ * generated successfully but later excluded" (see GenerateReviewStep) — the
+ * component generated fine locally but failed server-side validation.
+ */
+export async function rejectComponentsByName(sessionId, names, opts = {}) {
+    if (names.length === 0)
+        return;
+    const db = openPipelineDb();
+    try {
+        const placeholders = names.map(() => '?').join(',');
+        db.prepare(`UPDATE raw_components SET status = 'generate-rejected' WHERE session_id = ? AND name IN (${placeholders})`).run(sessionId, ...names);
+    }
+    finally {
+        db.close();
+    }
+    const artifactsRoot = opts.artifactsRoot ?? getRefineArtifactsRoot();
+    const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+    const nameSet = new Set(names);
+    let snapshot;
+    try {
+        snapshot = JSON.parse(await readFile(paths.statePath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const components = snapshot.components.map((c) => (nameSet.has(c.name) ? { ...c, status: 'rejected' } : c));
+    await saveReviewState(paths.statePath, { ...snapshot, components });
+}
 function resolveSessionId(sessionFlag) {
     if (sessionFlag)
         return sessionFlag;
@@ -194,8 +380,9 @@ export function registerAnalyzeEditCommand(program) {
         .option('--accept-all', 'Alias for --select-all', false)
         .option('--reject <pattern>', 'Alias for --deselect <pattern> (repeatable)', collect, [])
         .option('--patch <path>', 'Path to a JSON patch file for structured component overrides')
-        .option('--exclude-invalid', 'Auto-reject components with validation errors when bulk-selecting (no-op without --select-all)')
-        .action(async ({ session: sessionFlag, projectRoot, acceptAll, selectAll, reject, deselect, select, patch, excludeInvalid, }) => {
+        .option('--exclude-invalid', 'With --select-all: auto-reject components with validation errors instead of failing loud (opt-in bypass for the gate)')
+        .option('--exclude-components <names>', 'Comma-separated component names to force-reject, regardless of other selection flags')
+        .action(async ({ session: sessionFlag, projectRoot, acceptAll, selectAll, reject, deselect, select, patch, excludeInvalid, excludeComponents, }) => {
         const sessionId = resolveSessionId(sessionFlag);
         const db = openPipelineDb();
         let rawComponentCount = 0;
@@ -216,7 +403,8 @@ export function registerAnalyzeEditCommand(program) {
             (reject ?? []).length > 0 ||
             (deselect ?? []).length > 0 ||
             (select ?? []).length > 0 ||
-            !!patch;
+            !!patch ||
+            !!excludeComponents;
         let paths;
         let snapshot;
         try {
@@ -237,7 +425,9 @@ export function registerAnalyzeEditCommand(program) {
         // Non-interactive path
         if (nonInteractive) {
             const stepDb = openPipelineDb();
-            const stepId = createStep(stepDb, sessionId, 'analyze select', { sessionId });
+            const stepId = createStep(stepDb, sessionId, 'analyze select', {
+                sessionId,
+            });
             try {
                 await runNonInteractive(snapshot, {
                     session: sessionFlag,
@@ -249,6 +439,7 @@ export function registerAnalyzeEditCommand(program) {
                     select,
                     patch,
                     excludeInvalid,
+                    excludeComponents,
                 }, paths, sessionId);
                 updateStep(stepDb, stepId, 'complete', { sessionId });
             }

package/dist/src/analyze/select/tui/App.js

@@ -317,8 +317,7 @@ export function App({ sessionId, artifactsRoot, reviewRoot }) {
         onToggleHelp: () => setShowHelp((prev) => !prev),
     });
     // Must be before early returns — Rules of Hooks
-    const sessionSummary = useMemo(() => sortComponentsForSidebar((session?.components ?? [])
-        .map((c) => {
+    const sessionSummary = useMemo(() => sortComponentsForSidebar((session?.components ?? []).map((c) => {
         const counts = countValidationIssues(c.originalProposal);
         return {
             id: c.id,
@@ -330,13 +329,6 @@ export function App({ sessionId, artifactsRoot, reviewRoot }) {
             validationErrorCount: counts.errors,
             validationWarningCount: counts.warnings,
         };
-    })
-        .sort((a, b) => {
-        const aF = a.needsReview && a.status === 'needs-review' ? 0 : 1;
-        const bF = b.needsReview && b.status === 'needs-review' ? 0 : 1;
-        if (aF !== bF)
-            return aF - bF;
-        return (a.extractionConfidence ?? 6) - (b.extractionConfidence ?? 6);
     })), [session?.components, previewAnnotations]);
     if (loading) {
         return _jsx(Text, { children: "Loading session..." });

package/dist/src/analyze/select/tui/components/Sidebar.d.ts

@@ -11,7 +11,7 @@ type SidebarProps = {
     collapsed?: boolean;
     width?: number;
 };
-export declare function statusIcon(status: ReviewComponentStatus, validationErrorCount: number, validationWarningCount: number): string;
+export declare function statusIcon(status: ReviewComponentStatus, validationErrorCount: number, _validationWarningCount: number): string;
 export declare function statusColor(status: ReviewComponentStatus, validationErrorCount: number, validationWarningCount: number): string;
 export declare function sortComponentsForSidebar(components: ReviewComponentSummary[]): ReviewComponentSummary[];
 export declare function Sidebar({ components, selectedId, focused, scrollOffset, visibleCount, collapsed, width: widthProp, }: SidebarProps): React.ReactElement;

package/dist/src/analyze/select/tui/components/Sidebar.js

@@ -1,7 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
-export function statusIcon(status, validationErrorCount, validationWarningCount) {
-    if (validationErrorCount > 0 || validationWarningCount > 0)
+export function statusIcon(status, validationErrorCount, 
+// Warnings deliberately do NOT override the icon — the user's accept/reject
+// decision must remain visible. Color is already yellow via statusColor for
+// warning-only components, so the warning cue is preserved.
+_validationWarningCount) {
+    // Errors override — a structurally broken component should never render as ✓/✗.
+    if (validationErrorCount > 0)
         return '⚠';
     switch (status) {
         case 'accepted':
@@ -35,11 +40,29 @@ function truncateName(name, maxLen) {
         return name;
     return name.slice(0, maxLen) + '…';
 }
+/**
+ * Sort key for stable secondary ordering within a validation tier:
+ * needs-review components first, then by extractionConfidence ascending
+ * (lowest confidence first, null treated as highest = last). Used to be
+ * applied inline in App.tsx, then this helper sorted again — pulled in
+ * here so the sort happens once.
+ */
+function withinTierComparator(a, b) {
+    const aPending = a.needsReview && a.status === 'needs-review' ? 0 : 1;
+    const bPending = b.needsReview && b.status === 'needs-review' ? 0 : 1;
+    if (aPending !== bPending)
+        return aPending - bPending;
+    return (a.extractionConfidence ?? 6) - (b.extractionConfidence ?? 6);
+}
 export function sortComponentsForSidebar(components) {
     const withErrors = components.filter((c) => c.validationErrorCount > 0);
     const withWarnings = components.filter((c) => c.validationErrorCount === 0 && c.validationWarningCount > 0);
     const clean = components.filter((c) => c.validationErrorCount === 0 && c.validationWarningCount === 0);
-    return [...withErrors, ...withWarnings, ...clean];
+    return [
+        ...[...withErrors].sort(withinTierComparator),
+        ...[...withWarnings].sort(withinTierComparator),
+        ...[...clean].sort(withinTierComparator),
+    ];
 }
 export function Sidebar({ components, selectedId, focused, scrollOffset, visibleCount, collapsed = false, width: widthProp, }) {
     const sorted = sortComponentsForSidebar(components);