intent: QaCoverageIntent;

};

type QaCoverageFeatureSummary = {

type QaCoverageIdSummary = {

id: string;

scenarios: QaCoverageScenarioReference[];

};

coverageIdCount: number;

primaryCoverageIdCount: number;

secondaryCoverageIdCount: number;

features: QaCoverageFeatureSummary[];

overlappingCoverage: QaCoverageFeatureSummary[];

coverageIds: QaCoverageIdSummary[];

overlappingCoverage: QaCoverageIdSummary[];

missingCoverage: QaCoverageScenarioSummary[];

byTheme: Record<string, QaCoverageFeatureSummary[]>;

bySurface: Record<string, QaCoverageFeatureSummary[]>;

byTheme: Record<string, QaCoverageIdSummary[]>;

bySurface: Record<string, QaCoverageIdSummary[]>;

scenarioPacks: QaCoverageScenarioPackSummary[];

liveTransportLanes: LiveTransportCoverageLaneSummary[];

scorecardTaxonomy: QaScorecardTaxonomyReport;

.toSorted((left, right) => left.id.localeCompare(right.id));

}

function sortFeatures(features: readonly QaCoverageFeatureSummary[]) {

return features.toSorted((left, right) => left.id.localeCompare(right.id));

function sortCoverageIds(coverageIds: readonly QaCoverageIdSummary[]) {

return coverageIds.toSorted((left, right) => left.id.localeCompare(right.id));

}

function buildScenarioPackSummaries(

export function buildQaCoverageInventory(

scenarios: readonly QaSeedScenarioWithSource[],

): QaCoverageInventory {

const byCoverageId = new Map<string, QaCoverageFeatureSummary>();

const byCoverageId = new Map<string, QaCoverageIdSummary>();

const primaryCoverageIds = new Set<string>();

const secondaryCoverageIds = new Set<string>();

const missingCoverage: QaCoverageScenarioSummary[] = [];

const addCoverage = (

const addFeatureCoverage = (

scenario: QaSeedScenarioWithSource,

coverageIds: readonly string[] | undefined,

intent: QaCoverageIntent,

) => {

const summary = summarizeScenario(scenario);

for (const coverageId of coverageIds ?? []) {

const feature = byCoverageId.get(coverageId) ?? {

const coverage = byCoverageId.get(coverageId) ?? {

id: coverageId,

scenarios: [],

};

feature.scenarios.push({ ...summary, intent });

byCoverageId.set(coverageId, feature);

coverage.scenarios.push({ ...summary, intent });

byCoverageId.set(coverageId, coverage);

if (intent === "primary") {

primaryCoverageIds.add(coverageId);

} else {

missingCoverage.push(summarizeScenario(scenario));

continue;

}

addCoverage(scenario, scenario.coverage.primary, "primary");

addCoverage(scenario, scenario.coverage.secondary, "secondary");

addFeatureCoverage(scenario, scenario.coverage.primary, "primary");

addFeatureCoverage(scenario, scenario.coverage.secondary, "secondary");

}

const features = sortFeatures([...byCoverageId.values()]);

const overlappingCoverage = features.filter((feature) => feature.scenarios.length > 1);

const byTheme: Record<string, QaCoverageFeatureSummary[]> = {};

const bySurface: Record<string, QaCoverageFeatureSummary[]> = {};

const coverageIds = sortCoverageIds([...byCoverageId.values()]);

const overlappingCoverage = coverageIds.filter((coverage) => coverage.scenarios.length > 1);

const byTheme: Record<string, QaCoverageIdSummary[]> = {};

const bySurface: Record<string, QaCoverageIdSummary[]> = {};

for (const feature of features) {

const themes = new Set(feature.scenarios.map((scenario) => scenario.theme));

for (const coverage of coverageIds) {

const themes = new Set(coverage.scenarios.map((scenario) => scenario.theme));

for (const theme of themes) {

byTheme[theme] ??= [];

byTheme[theme].push({

...feature,

scenarios: feature.scenarios.filter((scenario) => scenario.theme === theme),

...coverage,

scenarios: coverage.scenarios.filter((scenario) => scenario.theme === theme),

});

}

const surfaces = new Set(feature.scenarios.flatMap((scenario) => scenario.surfaces));

const surfaces = new Set(coverage.scenarios.flatMap((scenario) => scenario.surfaces));

for (const surface of surfaces) {

bySurface[surface] ??= [];

bySurface[surface].push({

...feature,

scenarios: feature.scenarios.filter((scenario) => scenario.surfaces.includes(surface)),

...coverage,

scenarios: coverage.scenarios.filter((scenario) => scenario.surfaces.includes(surface)),

});

}

}

return {

scenarioCount: scenarios.length,

coverageIdCount: features.length,

coverageIdCount: coverageIds.length,

primaryCoverageIdCount: primaryCoverageIds.size,

secondaryCoverageIdCount: secondaryCoverageIds.size,

features,

coverageIds,

overlappingCoverage,

missingCoverage,

byTheme,

};

}

function pushFeatureLines(lines: string[], features: readonly QaCoverageFeatureSummary[]) {

for (const feature of sortFeatures(features)) {

const scenarios = feature.scenarios

function pushCoverageIdLines(lines: string[], coverageIds: readonly QaCoverageIdSummary[]) {

for (const coverage of sortCoverageIds(coverageIds)) {

const scenarios = coverage.scenarios

.map((scenario) => `${scenario.intent}: ${scenario.id} (${scenario.sourcePath})`)

.join(", ");

lines.push(`- ${feature.id}: ${scenarios}`);

lines.push(`- ${coverage.id}: ${scenarios}`);

}

}

const missing =

pack.missingScenarioIds.length > 0 ? pack.missingScenarioIds.join(", ") : "none";

lines.push(

`- ${pack.id} (${pack.title}): ${pack.scenarioIds.length} scenarios; coverage: ${pack.coverageIds.join(", ")}; missing scenarios: ${missing}`,

`- ${pack.id} (${pack.title}): ${pack.scenarioIds.length} scenarios; coverage IDs: ${pack.coverageIds.join(", ")}; missing scenarios: ${missing}`,

);

lines.push(` - scenarios: ${pack.scenarioIds.join(", ")}`);

}

}

function pushScorecardTaxonomyLines(lines: string[], report: QaScorecardTaxonomyReport) {

lines.push("## Scorecard Taxonomy", "");

lines.push(`- Mapping: ${report.taxonomyPath ?? "missing"}`);

lines.push(`- Mapping ID: ${report.taxonomyId ?? "missing"}`);

lines.push(`- Maturity taxonomy: ${report.taxonomy?.sourcePath ?? "missing"}`);

if (report.scoreSnapshotRef) {

lines.push(`- Maturity score snapshot: ${report.scoreSnapshotRef}`);

}

lines.push(`- Taxonomy: ${report.taxonomyPath ?? "missing"}`);

lines.push(`- Categories: ${report.categoryCount}`);

lines.push(`- Profiles: ${report.profileCount}`);

lines.push(

`- Categories: ${report.categoryCount} (${report.ltsIncludedCategoryCount} LTS-included, ${report.deferredCategoryCount} deferred, ${report.advisoryCategoryCount} advisory)`,

`- Fulfilled taxonomy categories: ${report.fulfilledCategoryCount}/${report.requiredCategoryCount} (${report.categoryFulfillmentPercent}%)`,

);

lines.push(`- Profiles: ${report.profileCount}`);

lines.push(`- Release-blocking categories: ${report.releaseBlockingCategoryCount}`);

lines.push(`- Mapped coverage IDs: ${report.mappedCoverageIdCount}`);

lines.push(`- Mapped scenarios: ${report.mappedScenarioCount}`);

lines.push(`- Unmapped coverage IDs: ${report.unmappedCoverageIdCount}`);

lines.push(

`- Fulfilled taxonomy features: ${report.fulfilledFeatureCount}/${report.requiredFeatureCount} (${report.taxonomyFulfillmentPercent}%)`,

);

lines.push(`- Evidence refs: ${report.evidenceRefCount}`);

lines.push(`- Scenario coverage IDs: ${report.scenarioCoverageIdCount}`);

lines.push(`- Unmapped scenario coverage IDs: ${report.unmappedCoverageIdCount}`);

lines.push(`- Validation warnings: ${report.validationIssueCount}`, "");

if (report.profiles.length > 0) {

if (report.categories.length > 0) {

lines.push("### Category Mapping", "");

for (const category of report.categories) {

const blocking = category.releaseBlocking ? "release-blocking" : "non-blocking";

const coverage = category.coverageIds.length > 0 ? category.coverageIds.join(", ") : "none";

const scenarios =

category.scenarioRefs.length > 0 ? category.scenarioRefs.join(", ") : "none";

const coverageIds =

category.coverageIds.length > 0 ? category.coverageIds.join(", ") : "none";

const evidence =

category.evidence.length > 0

? category.evidence

.map((ref) => {

const target = ref.path ?? (ref.scenarioRefs.join("|") || "discovered");

return `${ref.role}:${ref.kind}:${target} (${ref.coverageId})`;

})

.join(", ")

: "none";

const profiles = category.profiles.length > 0 ? category.profiles.join(", ") : "none";

lines.push(

`- ${category.id} (${category.taxonomySurfaceId} / ${category.taxonomyCategoryName}; ${category.supportStatus}, ${blocking}, ${category.mappingStatus}): profiles: ${profiles}; coverage: ${coverage}; scenarios: ${scenarios}`,

`- ${category.id} (${category.taxonomySurfaceId} / ${category.taxonomyCategoryName}; ${category.mappingStatus}): profiles: ${profiles}; coverage IDs: ${coverageIds}; evidence: ${evidence}`,

);

}

lines.push("");

}

if (report.unmappedCoverageIds.length > 0) {

lines.push("### Unmapped Coverage IDs", "");

lines.push("### Unmapped Scenario Coverage IDs", "");

lines.push(report.unmappedCoverageIds.join(", "));

lines.push("");

}

"# QA Coverage Inventory",

"",

`- Scenarios: ${inventory.scenarioCount}`,

`- Coverage IDs: ${inventory.coverageIdCount}`,

`- Taxonomy coverage IDs: ${inventory.coverageIdCount}`,

`- Primary coverage IDs: ${inventory.primaryCoverageIdCount}`,

`- Secondary coverage IDs: ${inventory.secondaryCoverageIdCount}`,

`- Overlapping coverage IDs: ${inventory.overlappingCoverage.length}`,

lines.push("## By Theme", "");

for (const theme of Object.keys(inventory.byTheme).toSorted()) {

lines.push(`### ${theme}`, "");

pushFeatureLines(lines, inventory.byTheme[theme] ?? []);

pushCoverageIdLines(lines, inventory.byTheme[theme] ?? []);

lines.push("");

}

lines.push("## By Surface", "");

for (const surface of Object.keys(inventory.bySurface).toSorted()) {

lines.push(`### ${surface}`, "");

pushFeatureLines(lines, inventory.bySurface[surface] ?? []);

pushCoverageIdLines(lines, inventory.bySurface[surface] ?? []);

lines.push("");

}

if (inventory.overlappingCoverage.length > 0) {

lines.push("## Overlap", "");

pushFeatureLines(lines, inventory.overlappingCoverage);

pushCoverageIdLines(lines, inventory.overlappingCoverage);

lines.push("");

}

function scenarioMatchCommandGroups(matches: readonly QaScenarioSearchMatch[]) {

const groups = new Map<QaScenarioSearchMatch["executionKind"], QaScenarioSearchMatch[]>();

for (const match of matches) {

const existing = groups.get(match.executionKind) ?? [];

existing.push(match);

groups.set(match.executionKind, existing);

const group = groups.get(match.executionKind) ?? [];

group.push(match);

groups.set(match.executionKind, group);

}

const executionOrder: QaScenarioSearchMatch["executionKind"][] = ["flow", "vitest", "playwright"];

return executionOrder

.map((executionKind) => ({

executionKind,

matches: groups.get(executionKind) ?? [],

}))

.filter((group) => group.matches.length > 0);

return executionOrder.flatMap((executionKind) => {

const group = groups.get(executionKind);

return group && group.length > 0 ? [{ executionKind, matches: group }] : [];

});

}

export function renderQaScenarioMatchesMarkdownReport(params: {

query: string;

matches: readonly QaScenarioSearchMatch[];

}) {

const commandGroups = scenarioMatchCommandGroups(params.matches);

const lines = [

"# QA Scenario Matches",

"",

`- Query: ${params.query}`,

`- Matches: ${params.matches.length}`,

];

const commandGroups = scenarioMatchCommandGroups(params.matches);

if (commandGroups.length === 1) {

lines.push(`- Suite command: \`${formatSuiteCommand(commandGroups[0].matches)}\``);

} else if (commandGroups.length > 1) {

lines.push(` - surface: ${match.surfaces.join(", ")}`);

lines.push(

match.executionKind === "flow"

? " - execution: flow (qa-flow block)"

? " - execution: qa-flow"

: ` - execution: ${match.executionKind} ${match.executionPath ?? "missing"}`,

);

lines.push(` - coverage: ${match.coverageIds.join(", ") || "none"}`);

lines.push(` - coverage IDs: ${match.coverageIds.join(", ") || "none"}`);

lines.push(` - live requirements: ${formatOptionalScenarioMetadata(match)}`);

if (match.codeRefs.length > 0) {

lines.push(` - code refs: ${match.codeRefs.join(", ")}`);