@hs-x/cli 0.4.2-next.0 → 0.4.2

package/dist/commands/react.js

@@ -0,0 +1,884 @@
+import { relative } from 'node:path';
+import * as Args from '@effect/cli/Args';
+import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
+import { REACT_DOCTOR_COVERAGE, REACT_DOCTOR_RULE_COVERAGE, REACT_DOCTOR_RULE_METADATA, STUDIO_RULE_CATALOG, explainReactDoctorRule, scanReactProject, scanReactReview, scanReactWorkspace, } from '@hs-x/react-doctor';
+import { Effect, Option } from 'effect';
+import { cliError, exitWith } from '../cli-error.js';
+import { jsonOption, runHandler } from '../cli/kit.js';
+import { currentCliOutputFlags } from '../output-context.js';
+import { Cwd } from '../services/cwd.js';
+import { Reporter } from '../services/reporter.js';
+import { scanReactHealth, scanReactHealthProjects, scopeHubSpotReactReport, } from './react-health.js';
+const strictOption = Options.boolean('strict').pipe(Options.withDefault(false));
+const recursiveOption = Options.boolean('recursive').pipe(Options.withDefault(false));
+const hubspotOnlyOption = Options.boolean('hubspot-only').pipe(Options.withDefault(false));
+const scopeOption = Options.choice('scope', ['full', 'files', 'changed', 'lines']).pipe(Options.optional);
+const baseOption = Options.text('base').pipe(Options.optional);
+const deepOption = Options.boolean('deep').pipe(Options.withDefault(false));
+const stagedOption = Options.boolean('staged').pipe(Options.withDefault(false));
+const ciOption = Options.boolean('ci').pipe(Options.withDefault(false));
+const reactDoctorBaseCmd = Command.make('doctor', {
+    hubspotOnly: hubspotOnlyOption,
+    base: baseOption,
+    ci: ciOption,
+    deep: deepOption,
+    json: jsonOption,
+    recursive: recursiveOption,
+    scope: scopeOption,
+    staged: stagedOption,
+    strict: strictOption,
+}, (opts) => {
+    const verbose = currentCliOutputFlags().verbose;
+    return runHandler('react doctor', { json: opts.json, verbose }, reactDoctorBody({ ...opts, verbose }));
+});
+const whyLocationArg = Args.text({ name: 'file:line' });
+export const reactDoctorWhyCmd = Command.make('why', { json: jsonOption, location: whyLocationArg }, (opts) => runHandler('react doctor why', { json: opts.json }, reactDoctorWhyBody(opts.location, opts.json)));
+export const reactDoctorCmd = reactDoctorBaseCmd.pipe(Command.withSubcommands([reactDoctorWhyCmd]));
+const reactRulesBaseCmd = Command.make('rules', { json: jsonOption }, (opts) => runHandler('react rules', { json: opts.json }, Effect.gen(function* () {
+    const reporter = yield* Reporter;
+    const coverageById = new Map(REACT_DOCTOR_RULE_COVERAGE.map((coverage) => [coverage.id, coverage.status]));
+    const rules = STUDIO_RULE_CATALOG.map((rule) => ({
+        ...rule,
+        status: coverageById.get(rule.id) ?? 'pending',
+        ...(rule.id in REACT_DOCTOR_RULE_METADATA
+            ? {
+                findingKind: REACT_DOCTOR_RULE_METADATA[rule.id].kind,
+                platform: REACT_DOCTOR_RULE_METADATA[rule.id].platform,
+            }
+            : {}),
+    }));
+    if (opts.json) {
+        yield* reporter.data({ coverage: REACT_DOCTOR_COVERAGE, rules });
+        yield* reporter.done();
+        return;
+    }
+    yield* reporter.header('React Doctor rule coverage');
+    yield* reporter.rows([
+        {
+            key: 'implemented',
+            value: `${REACT_DOCTOR_COVERAGE.implemented} deterministic React checks`,
+            status: 'ok',
+        },
+        {
+            key: 'heuristic',
+            value: `${REACT_DOCTOR_COVERAGE.heuristic} context-sensitive rules`,
+            status: 'warn',
+        },
+        {
+            key: 'studio-only',
+            value: `${REACT_DOCTOR_COVERAGE.studioOnly} JSON-spec/runtime rules`,
+        },
+        {
+            key: 'pending',
+            value: `${REACT_DOCTOR_COVERAGE.pending} deterministic candidates`,
+            status: REACT_DOCTOR_COVERAGE.pending > 0 ? 'warn' : 'ok',
+        },
+    ]);
+    yield* reporter.info(`Studio catalog: ${REACT_DOCTOR_COVERAGE.catalogRules} rules`);
+    yield* reporter.info(`Source SHA-256: ${REACT_DOCTOR_COVERAGE.sourceSha256}`);
+    yield* reporter.done('Rule coverage loaded', 0, {
+        ok: REACT_DOCTOR_COVERAGE.implemented,
+        warn: REACT_DOCTOR_COVERAGE.heuristic + REACT_DOCTOR_COVERAGE.pending,
+    });
+})));
+const ruleIdArg = Args.text({ name: 'rule-id' });
+export const reactRulesExplainCmd = Command.make('explain', { json: jsonOption, ruleId: ruleIdArg }, (opts) => runHandler('react rules explain', { json: opts.json }, Effect.gen(function* () {
+    const reporter = yield* Reporter;
+    const explanation = yield* Effect.try({
+        try: () => explainReactDoctorRule(opts.ruleId.toUpperCase()),
+        catch: (cause) => cliError('HSX_E_INPUT_INVALID', cause instanceof Error ? cause.message : String(cause)),
+    });
+    if (opts.json) {
+        yield* reporter.data(explanation);
+        yield* reporter.done();
+        return;
+    }
+    yield* reporter.header(`${explanation.rule.id} · ${explanation.rule.category}`);
+    yield* reporter.rows([
+        {
+            key: explanation.enforcement,
+            value: explanation.rule.rule,
+            ...(explanation.enforcement === 'enforced'
+                ? { status: 'ok' }
+                : explanation.enforcement === 'unimplemented'
+                    ? { status: 'warn' }
+                    : {}),
+            detail: `${explanation.rule.severity} · ${explanation.status}`,
+            hint: `Source: ${explanation.rule.source}`,
+        },
+    ]);
+    for (const source of explanation.sourceDocuments) {
+        yield* reporter.info(`${source.name}${source.scope.length > 0 ? ` · scope: ${source.scope.join(', ')}` : ''}`);
+    }
+    yield* reporter.info(explanation.agent.instruction);
+    yield* reporter.info('Use --json to include the complete versioned source guidance.');
+    yield* reporter.done('Rule explanation loaded');
+})));
+export const reactRulesCmd = reactRulesBaseCmd.pipe(Command.withSubcommands([reactRulesExplainCmd]));
+export const reactReviewCmd = Command.make('review', { deep: deepOption, json: jsonOption }, (opts) => runHandler('react review', { json: opts.json }, Effect.gen(function* () {
+    const root = yield* Cwd;
+    const reporter = yield* Reporter;
+    const packet = yield* Effect.tryPromise({
+        try: () => scanReactReview({ root, deep: opts.deep }),
+        catch: (cause) => cliError('HSX_E_INTERNAL', cause instanceof Error ? cause.message : `React review failed: ${String(cause)}`),
+    });
+    if (opts.json) {
+        yield* reporter.data(packet);
+        yield* reporter.done();
+        return;
+    }
+    yield* reporter.header(packet.projectName ?? 'HubSpot React review');
+    yield* reporter.rows([
+        {
+            key: 'deterministic',
+            value: `${packet.deterministic.diagnostics.length} finding${packet.deterministic.diagnostics.length === 1 ? '' : 's'}`,
+            status: packet.deterministic.summary.errors > 0 ? 'fail' : 'ok',
+        },
+        {
+            key: 'agent-review',
+            value: `${packet.candidates.length} contextual candidate${packet.candidates.length === 1 ? '' : 's'}`,
+            status: packet.candidates.length > 0 ? 'warn' : 'ok',
+        },
+        {
+            key: 'reference',
+            value: `${packet.referenceRules.length} project-relevant heuristic rules`,
+        },
+        {
+            key: 'inventory',
+            value: `${packet.inventory.components.length} HubSpot/HS-UIX components · ${packet.filesScanned} files`,
+        },
+    ]);
+    for (const candidate of packet.candidates.slice(0, 12)) {
+        yield* reporter.info(`${candidate.ruleId} · ${candidate.question} · ${candidate.evidence.length} evidence location${candidate.evidence.length === 1 ? '' : 's'}`);
+    }
+    if (packet.candidates.length > 12) {
+        yield* reporter.info(`${packet.candidates.length - 12} more candidates are available in --json.`);
+    }
+    yield* reporter.info('Candidates never affect the doctor exit code. An agent must return violation, compliant, or needs-context with evidence.');
+    yield* reporter.done('Review packet ready', packet.deterministic.summary.errors > 0 ? 1 : 0, {
+        ok: packet.deterministic.diagnostics.length,
+        warn: packet.candidates.length,
+    });
+})));
+export const reactCmd = Command.make('react').pipe(Command.withSubcommands([reactDoctorCmd, reactReviewCmd, reactRulesCmd]));
+function reactDoctorBody(opts) {
+    return Effect.gen(function* () {
+        const root = yield* Cwd;
+        const reporter = yield* Reporter;
+        const scope = Option.getOrUndefined(opts.scope);
+        const base = Option.getOrUndefined(opts.base);
+        const reactHealthOptions = {
+            ...(scope ? { scope } : {}),
+            ...(base ? { base } : {}),
+            deep: opts.deep,
+            staged: opts.staged,
+            ci: opts.ci,
+        };
+        const unscopedReport = yield* Effect.tryPromise({
+            try: () => opts.recursive
+                ? scanReactWorkspace({ root, deep: opts.deep })
+                : scanReactProject({ root, deep: opts.deep }),
+            catch: (cause) => cliError('HSX_E_INTERNAL', cause instanceof Error ? cause.message : `React Doctor failed: ${String(cause)}`),
+        });
+        const report = yield* Effect.tryPromise({
+            try: () => scopeHubSpotReactReport(unscopedReport, reactHealthOptions),
+            catch: (cause) => cliError('HSX_E_INTERNAL', cause instanceof Error ? cause.message : `React scope failed: ${String(cause)}`),
+        });
+        const reactHealth = opts.hubspotOnly
+            ? []
+            : yield* Effect.tryPromise({
+                try: () => 'projects' in report
+                    ? scanReactHealthProjects(report.projects.map((project) => project.root), reactHealthOptions)
+                    : scanReactHealth(report.root, reactHealthOptions).then((health) => [health]),
+                catch: (cause) => cliError('HSX_E_INTERNAL', cause instanceof Error
+                    ? cause.message
+                    : `Upstream React Doctor failed: ${String(cause)}`),
+            });
+        const combinedSummary = combineSummary(report, reactHealth);
+        const exitCode = combinedSummary.errors > 0 || (opts.strict && combinedSummary.warnings > 0) ? 1 : 0;
+        if (opts.json) {
+            yield* reporter.data({
+                ...report,
+                reactHealth: {
+                    enabled: !opts.hubspotOnly,
+                    projects: reactHealth,
+                    summary: summarizeReactHealth(reactHealth),
+                },
+                combinedSummary,
+                mode: {
+                    scope: scope ?? (opts.staged ? 'files' : opts.ci ? 'changed' : 'full'),
+                    ...(base ? { base } : {}),
+                    staged: opts.staged,
+                    deep: opts.deep,
+                    ci: opts.ci,
+                },
+                strict: opts.strict,
+            });
+            yield* reporter.done(undefined, exitCode);
+            if (exitCode !== 0)
+                return yield* Effect.fail(exitWith(exitCode));
+            return;
+        }
+        if ('projects' in report) {
+            yield* renderWorkspaceReport(reporter, report, reactHealth, exitCode, opts.verbose);
+            if (exitCode !== 0)
+                return yield* Effect.fail(exitWith(exitCode));
+            return;
+        }
+        yield* renderProjectReport(reporter, report, reactHealth[0], exitCode, opts.verbose);
+        if (exitCode !== 0)
+            return yield* Effect.fail(exitWith(exitCode));
+    });
+}
+function reactDoctorWhyBody(input, json) {
+    return Effect.gen(function* () {
+        const root = yield* Cwd;
+        const reporter = yield* Reporter;
+        const location = yield* Effect.try({
+            try: () => parseWhyLocation(input, root),
+            catch: (cause) => cliError('HSX_E_INPUT_INVALID', cause instanceof Error ? cause.message : String(cause)),
+        });
+        const hubspot = yield* Effect.tryPromise({
+            try: () => scanReactProject({ root }),
+            catch: (cause) => cliError('HSX_E_INTERNAL', cause instanceof Error ? cause.message : String(cause)),
+        });
+        const react = yield* Effect.tryPromise({
+            try: () => scanReactHealth(root),
+            catch: (cause) => cliError('HSX_E_INTERNAL', cause instanceof Error ? cause.message : String(cause)),
+        });
+        const explanations = [
+            ...hubspot.diagnostics
+                .filter((diagnostic) => diagnosticAtLocation(diagnostic, location))
+                .map((diagnostic) => {
+                const metadata = REACT_DOCTOR_RULE_METADATA[diagnostic.ruleId];
+                return {
+                    engine: 'hubspot-uix',
+                    ruleId: diagnostic.ruleId,
+                    kind: diagnostic.kind,
+                    severity: diagnostic.severity,
+                    message: diagnostic.message,
+                    guidance: diagnostic.suggestion,
+                    source: diagnostic.source,
+                    platform: metadata.platform,
+                    projectPlatform: hubspot.platformVersion ?? null,
+                    location: `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}`,
+                };
+            }),
+            ...react.diagnostics
+                .filter((diagnostic) => diagnosticAtLocation(diagnostic, location))
+                .map((diagnostic) => ({
+                engine: 'react-doctor',
+                ruleId: diagnostic.ruleId,
+                kind: diagnostic.severity === 'error' ? 'error' : 'review',
+                severity: diagnostic.severity,
+                message: diagnostic.message,
+                guidance: diagnostic.suggestion,
+                category: diagnostic.category,
+                suppressionHint: diagnostic.suppressionHint ?? null,
+                relatedLocations: diagnostic.relatedLocations ?? [],
+                fixGroupId: diagnostic.fixGroupId ?? null,
+                url: diagnostic.url ?? null,
+                location: `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}`,
+            })),
+        ];
+        if (json) {
+            yield* reporter.data({
+                query: location,
+                explanations,
+                suppressedPatterns: explanations.length === 0 ? react.suppressedDiagnostics : [],
+            });
+            yield* reporter.done();
+            return;
+        }
+        yield* reporter.header(`Why · ${location.file}:${location.line}`);
+        if (explanations.length === 0) {
+            yield* reporter.info('No active finding starts at this location.');
+            if (react.suppressedDiagnostics.length > 0) {
+                yield* reporter.info(`${react.suppressedDiagnostics.length} upstream rule pattern${react.suppressedDiagnostics.length === 1 ? ' was' : 's were'} suppressed by HubSpot runtime exceptions; use --json to inspect them.`);
+            }
+            yield* reporter.done('No active finding at this location', 0, { warn: 1 });
+            return;
+        }
+        for (const explanation of explanations) {
+            yield* reporter.rows([
+                {
+                    key: explanation.ruleId,
+                    value: explanation.message,
+                    status: explanation.severity === 'error' ? 'fail' : 'warn',
+                    detail: explanation.engine === 'hubspot-uix' ? 'HubSpot UIX' : explanation.category,
+                    hint: [
+                        explanation.guidance,
+                        ...(explanation.engine === 'hubspot-uix'
+                            ? [
+                                `Source: ${explanation.source}`,
+                                ...(explanation.projectPlatform
+                                    ? [`Project platform: ${explanation.projectPlatform}`]
+                                    : []),
+                            ]
+                            : [
+                                ...(explanation.suppressionHint
+                                    ? [`Suppress: ${explanation.suppressionHint}`]
+                                    : []),
+                                ...(explanation.url ? [explanation.url] : []),
+                            ]),
+                    ].join(' · '),
+                },
+            ]);
+        }
+        yield* reporter.done(`${explanations.length} explanation${explanations.length === 1 ? '' : 's'}`);
+    });
+}
+function parseWhyLocation(input, root) {
+    const match = /^(.+?):(\d+)(?::(\d+))?$/.exec(input.trim());
+    if (!match?.[1] || !match[2]) {
+        throw new Error('Expected a source location like src/Card.tsx:42 or src/Card.tsx:42:7.');
+    }
+    const requested = match[1];
+    const file = requested.startsWith('/') ? relative(root, requested) : requested;
+    return {
+        file: file.replaceAll('\\', '/').replace(/^\.\//, ''),
+        line: Number(match[2]),
+        ...(match[3] ? { column: Number(match[3]) } : {}),
+    };
+}
+function diagnosticAtLocation(diagnostic, location) {
+    const file = diagnostic.file.replaceAll('\\', '/').replace(/^\.\//, '');
+    return (file === location.file &&
+        diagnostic.line === location.line &&
+        (location.column === undefined || diagnostic.column === location.column));
+}
+function renderProjectReport(reporter, report, reactHealth, exitCode, verbose) {
+    return Effect.gen(function* () {
+        yield* reporter.header(report.projectName ?? 'HubSpot React project');
+        const hubspotDiagnostics = report.diagnostics.map((diagnostic) => hubspotDisplayDiagnostic(diagnostic));
+        const displaySummary = combineFindingSummaries(summarizeDisplayDiagnostics(hubspotDiagnostics), summarizeDisplayDiagnostics(reactHealth?.diagnostics.map((diagnostic) => reactDisplayDiagnostic(diagnostic)) ?? []));
+        const platform = report.platformVersion ? ` · platform ${report.platformVersion}` : '';
+        const hubspotScan = yield* reporter.step(`HubSpot UIX · ${report.filesScanned} source files${platform}`);
+        if (report.filesScanned === 0) {
+            yield* hubspotScan.warn('no HubSpot React source found');
+        }
+        else if (report.diagnostics.length === 0) {
+            yield* hubspotScan.ok(`no issues detected by ${report.rulesEvaluated} of ${report.coverage.catalogRules} catalog rules`);
+        }
+        else {
+            const summary = findingSummary(summarizeDisplayDiagnostics(hubspotDiagnostics));
+            if (report.summary.errors > 0)
+                yield* hubspotScan.fail(summary);
+            else
+                yield* hubspotScan.warn(summary);
+            yield* renderDiagnosticGroups(reporter, hubspotDiagnostics, verbose);
+        }
+        if (reactHealth)
+            yield* renderReactHealthReport(reporter, reactHealth, verbose);
+        else
+            yield* reporter.info('Generic React health disabled by --hubspot-only.');
+        yield* renderDoctorNotes(reporter, report, reactHealth ? [reactHealth] : [], verbose);
+        yield* reporter.done(resultSummary(exitCode, displaySummary), exitCode);
+    });
+}
+function renderWorkspaceReport(reporter, report, reactHealth, exitCode, verbose) {
+    return Effect.gen(function* () {
+        yield* reporter.header('HubSpot React workspace');
+        const hubspotDiagnostics = [];
+        for (const project of report.projects) {
+            for (const diagnostic of project.diagnostics) {
+                hubspotDiagnostics.push(hubspotDisplayDiagnostic(diagnostic, `${project.projectName ?? project.root}${project.platformVersion ? ` · ${project.platformVersion}` : ''}`));
+            }
+        }
+        const projectByRoot = new Map(report.projects.map((project) => [project.root, project.projectName ?? project.root]));
+        const reactDiagnostics = reactHealth.flatMap((health) => health.diagnostics.map((diagnostic) => reactDisplayDiagnostic(diagnostic, projectByRoot.get(health.root) ?? health.root)));
+        const displaySummary = combineFindingSummaries(summarizeDisplayDiagnostics(hubspotDiagnostics), summarizeDisplayDiagnostics(reactDiagnostics));
+        const hubspotScan = yield* reporter.step(`HubSpot UIX · ${report.projectsScanned} projects · ${report.filesScanned} source files`);
+        if (report.projectsScanned === 0) {
+            yield* hubspotScan.warn('no hsproject.json projects found');
+            yield* reporter.done('Nothing to scan', 0, { warn: 1 });
+            return;
+        }
+        if (report.summary.errors === 0 && report.summary.warnings === 0) {
+            yield* hubspotScan.ok(`no issues detected by ${report.rulesEvaluated} of ${report.coverage.catalogRules} catalog rules`);
+        }
+        else {
+            const summary = findingSummary(summarizeDisplayDiagnostics(hubspotDiagnostics));
+            if (report.summary.errors > 0)
+                yield* hubspotScan.fail(summary);
+            else
+                yield* hubspotScan.warn(summary);
+            yield* renderDiagnosticGroups(reporter, hubspotDiagnostics, verbose);
+        }
+        if (reactHealth.length > 0) {
+            yield* renderReactHealthWorkspace(reporter, report, reactHealth, verbose);
+        }
+        else
+            yield* reporter.info('Generic React health disabled by --hubspot-only.');
+        yield* renderDoctorNotes(reporter, report, reactHealth, verbose);
+        yield* reporter.done(resultSummary(exitCode, displaySummary), exitCode);
+    });
+}
+function renderReactHealthReport(reporter, report, verbose) {
+    return Effect.gen(function* () {
+        const scan = yield* reporter.step(`React health · ${report.filesScanned} React files${reactHealthModeSuffix(report)}`);
+        if (report.status === 'skipped') {
+            yield* scan.warn(`skipped · ${report.reason ?? 'React project not detected'}`);
+            return;
+        }
+        const diagnostics = report.diagnostics.map((diagnostic) => reactDisplayDiagnostic(diagnostic));
+        const displaySummary = summarizeDisplayDiagnostics(diagnostics);
+        if (report.diagnostics.length === 0)
+            yield* scan.ok('no upstream issues');
+        else if (report.summary.errors > 0)
+            yield* scan.fail(findingSummary(displaySummary));
+        else
+            yield* scan.warn(findingSummary(displaySummary));
+        if (report.diagnostics.length > 0) {
+            yield* renderDiagnosticGroups(reporter, diagnostics, verbose);
+        }
+        if (verbose)
+            yield* renderReactSuppressions(reporter, report);
+    });
+}
+function renderReactHealthWorkspace(reporter, hubspot, reports, verbose) {
+    return Effect.gen(function* () {
+        const summary = summarizeReactHealth(reports);
+        const scanned = reports.filter((report) => report.status === 'scanned');
+        const skipped = reports.length - scanned.length;
+        const files = scanned.reduce((total, report) => total + report.filesScanned, 0);
+        const scan = yield* reporter.step(`React health · ${scanned.length} projects · ${files} React files${scanned[0] ? reactHealthModeSuffix(scanned[0]) : ''}`);
+        const projectByRoot = new Map(hubspot.projects.map((project) => [project.root, project.projectName ?? project.root]));
+        const diagnostics = reports.flatMap((report) => report.diagnostics.map((diagnostic) => reactDisplayDiagnostic(diagnostic, projectByRoot.get(report.root) ?? report.root)));
+        const displaySummary = summarizeDisplayDiagnostics(diagnostics);
+        if (scanned.length === 0)
+            yield* scan.warn(`all ${skipped} projects skipped`);
+        else if (summary.errors > 0)
+            yield* scan.fail(findingSummary(displaySummary));
+        else if (summary.warnings > 0)
+            yield* scan.warn(findingSummary(displaySummary));
+        else
+            yield* scan.ok(skipped > 0 ? `no issues · ${skipped} skipped` : 'no upstream issues');
+        if (diagnostics.length > 0) {
+            yield* renderDiagnosticGroups(reporter, diagnostics, verbose);
+        }
+        if (verbose) {
+            for (const report of reports)
+                yield* renderReactSuppressions(reporter, report);
+        }
+        if (skipped > 0)
+            yield* reporter.info(`React health skipped ${skipped} non-React projects.`);
+    });
+}
+function reactHealthModeSuffix(report) {
+    const modes = [];
+    if (report.staged)
+        modes.push('staged');
+    else if (report.scope !== 'full') {
+        modes.push(report.baseRef ? `${report.scope} vs ${report.baseRef}` : report.scope);
+    }
+    if (report.deep)
+        modes.push('deep');
+    if (report.ci)
+        modes.push('CI');
+    return modes.length > 0 ? ` · ${modes.join(' · ')}` : '';
+}
+function summarizeReactHealth(reports) {
+    return reports.reduce((summary, report) => ({
+        errors: summary.errors + report.summary.errors,
+        reviews: summary.reviews + report.summary.warnings,
+        recommendations: summary.recommendations,
+        warnings: summary.warnings + report.summary.warnings,
+    }), { errors: 0, reviews: 0, recommendations: 0, warnings: 0 });
+}
+function combineFindingSummaries(left, right) {
+    return {
+        errors: left.errors + right.errors,
+        reviews: left.reviews + right.reviews,
+        recommendations: left.recommendations + right.recommendations,
+        warnings: left.warnings + right.warnings,
+    };
+}
+function renderReactSuppressions(reporter, report) {
+    return Effect.gen(function* () {
+        for (const suppression of report.suppressedDiagnostics) {
+            yield* reporter.info(`Suppressed ${suppression.count} ${suppression.ruleId}: ${suppression.reason}`);
+        }
+    });
+}
+function combineSummary(report, reactHealth) {
+    const react = summarizeReactHealth(reactHealth);
+    const hubspot = report.summary;
+    return {
+        errors: hubspot.errors + react.errors,
+        reviews: hubspot.reviews + react.reviews,
+        recommendations: hubspot.recommendations + react.recommendations,
+        warnings: hubspot.warnings + react.warnings,
+        hubspot,
+        react,
+    };
+}
+function findingSummary(summary) {
+    const findings = [];
+    if (summary.errors > 0)
+        findings.push(`${summary.errors} error${summary.errors === 1 ? '' : 's'}`);
+    if (summary.reviews > 0) {
+        findings.push(`${summary.reviews} review${summary.reviews === 1 ? '' : 's'}`);
+    }
+    if (summary.recommendations > 0) {
+        findings.push(`${summary.recommendations} recommendation${summary.recommendations === 1 ? '' : 's'}`);
+    }
+    return findings.length > 0 ? findings.join(' · ') : 'no issues';
+}
+function resultSummary(exitCode, summary) {
+    const outcome = exitCode !== 0
+        ? 'Scan failed'
+        : summary.reviews > 0
+            ? 'Scan passed with review items'
+            : summary.recommendations > 0
+                ? 'Scan passed with HS-UIX recommendations'
+                : 'Scan passed';
+    const findings = findingSummary(summary);
+    return findings === 'no issues' ? outcome : `${findings} · ${outcome}`;
+}
+function summarizeDisplayDiagnostics(diagnostics) {
+    const clusters = new Map();
+    for (const diagnostic of addDiagnosticRelations(diagnostics)) {
+        clusters.set(diagnosticFamilyKey(diagnostic, false), diagnostic.kind);
+    }
+    let errors = 0;
+    let reviews = 0;
+    let recommendations = 0;
+    for (const kind of clusters.values()) {
+        if (kind === 'error')
+            errors += 1;
+        else if (kind === 'review')
+            reviews += 1;
+        else
+            recommendations += 1;
+    }
+    return {
+        errors,
+        reviews,
+        recommendations,
+        warnings: reviews + recommendations,
+    };
+}
+function reactDisplayDiagnostic(diagnostic, project) {
+    return {
+        group: `${project ? `${project} · ` : ''}${diagnostic.file}`,
+        ruleId: diagnostic.ruleId.replace(/^react-doctor\//, ''),
+        severity: diagnostic.severity,
+        kind: diagnostic.severity === 'error' ? 'error' : 'review',
+        compactValue: normalizeDiagnosticText(diagnostic.title),
+        verboseValue: `${normalizeDiagnosticText(diagnostic.title)}: ${normalizeDiagnosticText(diagnostic.message)}`,
+        location: `${diagnostic.line}:${diagnostic.column}`,
+        context: diagnostic.category,
+        verboseHint: [
+            `${diagnostic.severity === 'error' ? 'Fix' : 'Review'}: ${normalizeDiagnosticText(diagnostic.suggestion)}`,
+            ...(diagnostic.suppressionHint
+                ? [`Suppress: ${normalizeDiagnosticText(diagnostic.suppressionHint)}`]
+                : []),
+            ...(diagnostic.url ? [diagnostic.url] : []),
+        ].join(' · '),
+        ...(diagnostic.fixGroupId ? { fixGroupId: diagnostic.fixGroupId } : {}),
+        ...(diagnostic.relatedLocations?.length
+            ? {
+                relatedLocations: diagnostic.relatedLocations.map((location) => `${location.file}:${location.line}:${location.column} (${normalizeDiagnosticText(location.message)})`),
+            }
+            : {}),
+    };
+}
+function hubspotDisplayDiagnostic(diagnostic, project) {
+    return {
+        group: `${project ? `${project} · ` : ''}${diagnostic.file}`,
+        ruleId: diagnostic.ruleId,
+        severity: diagnostic.severity,
+        kind: diagnostic.kind,
+        compactValue: normalizeDiagnosticText(diagnostic.suggestion),
+        verboseValue: normalizeDiagnosticText(diagnostic.message),
+        location: `${diagnostic.line}:${diagnostic.column}`,
+        verboseHint: `${diagnostic.kind === 'error' ? 'Fix' : diagnostic.kind === 'review' ? 'Review' : 'Recommendation'}: ${normalizeDiagnosticText(diagnostic.suggestion)} · Source: ${diagnostic.source}`,
+    };
+}
+function renderDiagnosticGroups(reporter, diagnostics, verbose) {
+    return Effect.gen(function* () {
+        const relatedDiagnostics = addDiagnosticRelations(diagnostics);
+        const useFamilyView = !verbose && diagnosticLocationCount(relatedDiagnostics) > 24;
+        for (const section of FINDING_SECTIONS) {
+            const sectionDiagnostics = relatedDiagnostics.filter((diagnostic) => diagnostic.kind === section.kind);
+            if (sectionDiagnostics.length === 0)
+                continue;
+            const findingCount = new Set(sectionDiagnostics.map((diagnostic) => diagnosticFamilyKey(diagnostic, false))).size;
+            const locationCount = diagnosticLocationCount(sectionDiagnostics);
+            const findingLabel = useFamilyView
+                ? `${findingCount} fix ${findingCount === 1 ? 'family' : 'families'} · ${locationCount} locations`
+                : findingCount === locationCount
+                    ? `${findingCount} finding${findingCount === 1 ? '' : 's'}`
+                    : `${findingCount} finding${findingCount === 1 ? '' : 's'} · ${locationCount} locations`;
+            yield* reporter.rows([{ key: section.label, value: findingLabel }]);
+            if (useFamilyView)
+                yield* reporter.rows(diagnosticFamilyRows(sectionDiagnostics));
+            else
+                yield* renderFileGroups(reporter, sectionDiagnostics, verbose);
+        }
+    });
+}
+function addDiagnosticRelations(diagnostics) {
+    return diagnostics.map((diagnostic) => {
+        if (diagnostic.ruleId !== 'TBL-01' && diagnostic.ruleId !== 'TBL-08') {
+            return diagnostic;
+        }
+        const context = [diagnostic.context, 'if keeping raw Table'].filter(Boolean).join(' · ');
+        return { ...diagnostic, context };
+    });
+}
+const FINDING_SECTIONS = [
+    { kind: 'error', label: 'Errors' },
+    { kind: 'review', label: 'Review' },
+    { kind: 'recommendation', label: 'HS-UIX recommendations' },
+];
+function renderFileGroups(reporter, diagnostics, verbose) {
+    return Effect.gen(function* () {
+        const byGroup = new Map();
+        for (const diagnostic of diagnostics) {
+            const group = byGroup.get(diagnostic.group) ?? [];
+            group.push(diagnostic);
+            byGroup.set(diagnostic.group, group);
+        }
+        const groups = [...byGroup.entries()].sort(([leftLabel], [rightLabel]) => leftLabel.localeCompare(rightLabel));
+        for (const [group, findings] of groups) {
+            // A blank-key row keeps the file on the same rail as its findings while
+            // leaving status glyphs and rule IDs to carry the actionable hierarchy.
+            yield* reporter.rows([{ key: '', value: group }]);
+            const sorted = [...findings].sort((left, right) => {
+                if (left.severity !== right.severity)
+                    return left.severity === 'error' ? -1 : 1;
+                return left.location.localeCompare(right.location, undefined, {
+                    numeric: true,
+                });
+            });
+            yield* reporter.rows(diagnosticRows(sorted, verbose));
+        }
+    });
+}
+function diagnosticRows(diagnostics, verbose) {
+    const combined = new Map();
+    for (const diagnostic of diagnostics) {
+        const key = diagnosticClusterKey(diagnostic, verbose);
+        const existing = combined.get(key);
+        const locations = [diagnostic.location, ...(diagnostic.relatedLocations ?? [])];
+        if (existing)
+            existing.locations.push(...locations);
+        else
+            combined.set(key, { diagnostic, locations });
+    }
+    return [...combined.values()].map(({ diagnostic, locations }) => ({
+        key: diagnostic.ruleId,
+        value: verbose ? diagnostic.verboseValue : diagnostic.compactValue,
+        status: diagnostic.severity === 'error' ? 'fail' : 'warn',
+        detail: diagnosticDetail(locations, diagnostic.context),
+        ...(verbose ? { hint: diagnostic.verboseHint } : {}),
+    }));
+}
+function diagnosticClusterKey(diagnostic, verbose) {
+    if (diagnostic.fixGroupId) {
+        return [diagnostic.group, diagnostic.severity, diagnostic.fixGroupId].join('\0');
+    }
+    return [
+        diagnostic.group,
+        diagnostic.severity,
+        diagnostic.ruleId,
+        verbose ? diagnostic.verboseValue : diagnostic.compactValue,
+        diagnostic.context ?? '',
+    ].join('\0');
+}
+function diagnosticFamilyKey(diagnostic, verbose) {
+    if (diagnostic.fixGroupId) {
+        return [diagnostic.severity, diagnostic.fixGroupId].join('\0');
+    }
+    return [
+        diagnostic.severity,
+        diagnostic.ruleId,
+        verbose ? diagnostic.verboseValue : diagnostic.compactValue,
+        diagnostic.context ?? '',
+    ].join('\0');
+}
+function diagnosticFamilyRows(diagnostics) {
+    const families = new Map();
+    for (const diagnostic of diagnostics) {
+        const key = diagnosticFamilyKey(diagnostic, false);
+        const family = families.get(key) ?? [];
+        family.push(diagnostic);
+        families.set(key, family);
+    }
+    return [...families.values()]
+        .sort((left, right) => {
+        const leftDiagnostic = left[0];
+        const rightDiagnostic = right[0];
+        if (!leftDiagnostic || !rightDiagnostic)
+            return 0;
+        if (leftDiagnostic.severity !== rightDiagnostic.severity) {
+            return leftDiagnostic.severity === 'error' ? -1 : 1;
+        }
+        return leftDiagnostic.ruleId.localeCompare(rightDiagnostic.ruleId);
+    })
+        .flatMap((family) => {
+        const diagnostic = family[0];
+        if (!diagnostic)
+            return [];
+        return [
+            {
+                key: diagnostic.ruleId,
+                value: diagnostic.compactValue,
+                status: diagnostic.severity === 'error' ? 'fail' : 'warn',
+                detail: diagnosticFamilyDetail(family, diagnostic.context),
+            },
+        ];
+    });
+}
+function diagnosticFamilyDetail(diagnostics, context) {
+    const locationsByFile = new Map();
+    for (const diagnostic of diagnostics) {
+        const locations = locationsByFile.get(diagnostic.group) ?? [];
+        locations.push(diagnostic.location, ...(diagnostic.relatedLocations ?? []));
+        locationsByFile.set(diagnostic.group, locations);
+    }
+    const entries = [...locationsByFile.entries()];
+    const previews = entries.slice(0, 2).map(([file, locations]) => {
+        const shown = locations.slice(0, 3);
+        const remaining = locations.length - shown.length;
+        return `${file} ${shown.join(', ')}${remaining > 0 ? ` +${remaining}` : ''}`;
+    });
+    const remainingFiles = entries.length - previews.length;
+    const locationCount = diagnosticLocationCount(diagnostics);
+    return [
+        `${entries.length} file${entries.length === 1 ? '' : 's'} · ${locationCount} location${locationCount === 1 ? '' : 's'}`,
+        ...previews,
+        ...(remainingFiles > 0 ? [`+${remainingFiles} files`] : []),
+        ...(context ? [context] : []),
+    ].join(' · ');
+}
+function diagnosticLocationCount(diagnostics) {
+    return diagnostics.reduce((total, diagnostic) => total + 1 + (diagnostic.relatedLocations?.length ?? 0), 0);
+}
+function diagnosticDetail(locations, context) {
+    return [locations.join(', '), ...(context ? [context] : [])].join(' · ');
+}
+function normalizeDiagnosticText(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function renderDoctorNotes(reporter, report, reactHealth, verbose) {
+    return Effect.gen(function* () {
+        const reactSummary = summarizeReactHealth(reactHealth);
+        const hasFindings = report.summary.errors +
+            report.summary.warnings +
+            reactSummary.errors +
+            reactSummary.warnings >
+            0;
+        if (!verbose) {
+            if (hasFindings)
+                yield* reporter.info('Run again with --verbose for explanations and guidance.');
+            return;
+        }
+        const versions = [
+            ...new Set(reactHealth
+                .map((health) => health.engineVersion)
+                .filter((version) => version !== undefined)),
+        ];
+        if (versions.length > 0) {
+            yield* reporter.info(`Upstream React Doctor v${versions.join(', ')} · offline score and telemetry disabled`);
+        }
+        yield* reporter.info('HubSpot rule IDs map to the shared HS-UIX Studio standards.');
+        yield* reporter.info(coverageText(report));
+    });
+}
+function coverageText(report) {
+    const { coverage } = report;
+    return `Coverage: ${coverage.implemented} implemented · ${coverage.heuristic} heuristic · ${coverage.studioOnly} Studio-only · ${coverage.pending} pending`;
+}
+export function reactHelpText() {
+    return `hs-x react
+
+Inspect HubSpot React UI extensions with the shared HS-UIX standards.
+
+Commands:
+  hs-x react doctor [options]                Scan generic React and HubSpot UIX health
+  hs-x react doctor why <file:line>           Explain why a finding fired
+  hs-x react review [--deep] [--json]        Build an agent-facing contextual review packet
+  hs-x react rules [--json]                  Show catalog coverage and rule status
+  hs-x react rules explain <rule-id>          Explain one rule with versioned source guidance
+`;
+}
+export function reactDoctorHelpText() {
+    return `hs-x react doctor
+
+Run generic React health checks plus HubSpot UI-extension checks without an
+HS-X login, Cloudflare account, network connection, or project migration.
+Generic checks include hooks, memoization, correctness, performance, and code
+quality. HubSpot findings use stable rule IDs from the shared HS-UIX Studio catalog.
+Platform/runtime errors fail by default; contextual findings appear under Review,
+and library adoption guidance appears under HS-UIX recommendations.
+
+Flags:
+  --cwd <path>              Project directory (defaults to current working directory)
+  --recursive               Discover every nested hsproject.json project
+  --scope <mode>            full, files, changed, or lines (default: full)
+  --base <ref>              Git base ref for files, changed, or lines scope
+  --staged                  Scan only files staged for commit
+  --ci                      Scan only findings introduced against the Git base
+  --deep                    Include archived source plus dead files, exports, dependencies, and cycles
+  --strict                  Fail on Review and HS-UIX recommendations too
+  --hubspot-only            Skip generic React health checks
+  --verbose                 Show full explanations and guidance
+  --json                    Emit structured JSON output
+`;
+}
+export function reactDoctorWhyHelpText() {
+    return `hs-x react doctor why <file:line>
+
+Explain every active HubSpot UIX and generic React finding that starts at a
+source location. HubSpot explanations include the shared source, platform gate,
+and project platform. Generic explanations include suppression guidance,
+related locations, fix-group identity, and the upstream rule reference.
+
+Examples:
+  hs-x react doctor why src/app/cards/Card.tsx:42
+  hs-x react doctor why src/app/cards/Card.tsx:42:7 --json
+
+Flags:
+  --cwd <path>              Project directory (defaults to current working directory)
+  --json                    Emit structured JSON output
+`;
+}
+export function reactRulesHelpText() {
+    return `hs-x react rules
+
+Show how every rule in the shared HS-UIX Studio catalog is handled by the
+React Doctor: implemented, heuristic, Studio-only, or pending.
+
+Flags:
+  --json                    Emit all catalog rules and coverage statuses
+`;
+}
+export function reactRulesExplainHelpText() {
+    return `hs-x react rules explain <rule-id>
+
+Explain one shared Studio rule, how React Doctor enforces it, the allowed agent
+verdicts, and the complete versioned source guidance in JSON mode.
+
+Flags:
+  --json                    Include the complete source documents and agent contract
+`;
+}
+export function reactReviewHelpText() {
+    return `hs-x react review
+
+Build a project-aware review packet for contextual HS-UIX rules. The packet
+contains deterministic findings, component evidence, relevant heuristic
+candidates, and the versioned Studio source documents an agent must evaluate.
+Candidates never affect the React Doctor exit code.
+
+Flags:
+  --cwd <path>              Project directory (defaults to current working directory)
+  --deep                    Include conventional archive and archived source trees
+  --json                    Emit the complete agent review packet
+`;
+}
+//# sourceMappingURL=react.js.map