kibi-cli 0.12.8 → 0.16.1

package/src/public/impact/coverage-depth-quality.ts

@@ -0,0 +1,268 @@
+import type {
+  ExtractedEntity,
+  ExtractionResult,
+} from "../../extractors/markdown.js";
+import type { QualityDiagnostic } from "./types.js";
+
+type ReviewableCoverageDepth =
+  | "unit_only"
+  | "open_or_nonpassing_tests_only"
+  | "scenario_only_no_test"
+  | "no_test_evidence";
+
+type CoverageDepth =
+  | ReviewableCoverageDepth
+  | "direct_passing_integration"
+  | "scenario_passing_integration"
+  | "direct_passing_e2e"
+  | "scenario_passing_e2e";
+
+type RequirementCoverage = {
+  readonly requirement: ExtractedEntity;
+  readonly scenarioCount: number;
+  readonly directTests: readonly ExtractedEntity[];
+  readonly scenarioTests: readonly ExtractedEntity[];
+};
+
+type RelationshipLookup = {
+  readonly result: ExtractionResult;
+  readonly relationshipType: string;
+  readonly type: string;
+  readonly entities: ReadonlyMap<string, ExtractedEntity>;
+};
+
+type IncomingLookup = {
+  readonly manifestResults: readonly ExtractionResult[];
+  readonly targetId: string;
+  readonly relationshipType: string;
+  readonly type: string;
+};
+
+function entitiesById(
+  manifestResults: readonly ExtractionResult[],
+): ReadonlyMap<string, ExtractedEntity> {
+  return new Map(
+    manifestResults.map((result) => [result.entity.id, result.entity]),
+  );
+}
+
+function outgoingTargets(
+  lookup: RelationshipLookup,
+): readonly ExtractedEntity[] {
+  return lookup.result.relationships.flatMap((relationship) => {
+    if (relationship.type !== lookup.relationshipType) return [];
+    const target = lookup.entities.get(relationship.to);
+    return target?.type === lookup.type ? [target] : [];
+  });
+}
+
+function incomingSources(lookup: IncomingLookup): readonly ExtractedEntity[] {
+  return lookup.manifestResults.flatMap((result) => {
+    if (result.entity.type !== lookup.type) return [];
+    return result.relationships.some(
+      (relationship) =>
+        relationship.type === lookup.relationshipType &&
+        relationship.to === lookup.targetId,
+    )
+      ? [result.entity]
+      : [];
+  });
+}
+
+function uniqueEntities(
+  entities: readonly ExtractedEntity[],
+): readonly ExtractedEntity[] {
+  return [
+    ...new Map(entities.map((entity) => [entity.id, entity])).values(),
+  ].toSorted((left, right) => left.id.localeCompare(right.id));
+}
+
+function testScope(test: ExtractedEntity): string {
+  if (test.verification_scope !== undefined) return test.verification_scope;
+  if (test.tags?.some((tag) => tag.toLowerCase() === "e2e") === true) {
+    return "end_to_end";
+  }
+  return test.source.toLowerCase().includes("e2e") ? "end_to_end" : "unknown";
+}
+
+function passingTests(
+  tests: readonly ExtractedEntity[],
+): readonly ExtractedEntity[] {
+  return tests.filter((test) => test.status === "passing");
+}
+
+function classifyCoverageDepth(coverage: RequirementCoverage): CoverageDepth {
+  const allTests = uniqueEntities([
+    ...coverage.directTests,
+    ...coverage.scenarioTests,
+  ]);
+  const directPassingTests = passingTests(coverage.directTests);
+  if (directPassingTests.some((test) => testScope(test) === "end_to_end")) {
+    return "direct_passing_e2e";
+  }
+  if (directPassingTests.some((test) => testScope(test) === "integration")) {
+    return "direct_passing_integration";
+  }
+
+  const scenarioPassingTests = passingTests(coverage.scenarioTests);
+  if (scenarioPassingTests.some((test) => testScope(test) === "end_to_end")) {
+    return "scenario_passing_e2e";
+  }
+  if (scenarioPassingTests.some((test) => testScope(test) === "integration")) {
+    return "scenario_passing_integration";
+  }
+
+  const allPassingTests = passingTests(allTests);
+  if (
+    allPassingTests.length > 0 &&
+    allPassingTests.every((test) => testScope(test) === "unit")
+  ) {
+    return "unit_only";
+  }
+
+  if (allTests.length > 0) return "open_or_nonpassing_tests_only";
+  if (coverage.scenarioCount > 0) return "scenario_only_no_test";
+  return "no_test_evidence";
+}
+
+function isReviewableCoverageDepth(
+  coverageDepth: CoverageDepth,
+): coverageDepth is ReviewableCoverageDepth {
+  return (
+    coverageDepth === "unit_only" ||
+    coverageDepth === "open_or_nonpassing_tests_only" ||
+    coverageDepth === "scenario_only_no_test" ||
+    coverageDepth === "no_test_evidence"
+  );
+}
+
+function uniqueStrings(values: readonly string[]): readonly string[] {
+  return [...new Set(values)].toSorted((left, right) =>
+    left.localeCompare(right),
+  );
+}
+
+function coverageDepthSuggestion(
+  coverageDepth: ReviewableCoverageDepth,
+): string {
+  if (coverageDepth === "unit_only") {
+    return "Keep unit coverage where appropriate; add or link a passing end-to-end or scenario-backed test when this behavior warrants e2e confidence.";
+  }
+  return "Add or link passing tests, preferably end-to-end or scenario-backed when this behavior warrants e2e confidence.";
+}
+
+function createDiagnostic(
+  coverage: RequirementCoverage,
+): QualityDiagnostic | undefined {
+  const coverageDepth = classifyCoverageDepth(coverage);
+  if (!isReviewableCoverageDepth(coverageDepth)) return undefined;
+
+  const allTests = uniqueEntities([
+    ...coverage.directTests,
+    ...coverage.scenarioTests,
+  ]);
+  return {
+    id: "coverage_depth_review",
+    severity: "review",
+    blocking: false,
+    category: "coverage",
+    entityId: coverage.requirement.id,
+    source: coverage.requirement.source,
+    files: [coverage.requirement.source],
+    message: `Requirement ${coverage.requirement.id} (${coverage.requirement.title}) has ${coverageDepth} coverage depth and may need stronger behavior-level evidence.`,
+    suggestion: coverageDepthSuggestion(coverageDepth),
+    evidence: {
+      requirementId: coverage.requirement.id,
+      title: coverage.requirement.title,
+      source: coverage.requirement.source,
+      coverageDepth,
+      directTests: coverage.directTests.map((test) => test.id),
+      scenarioTests: coverage.scenarioTests.map((test) => test.id),
+      testStatuses: uniqueStrings(allTests.map((test) => test.status)),
+      verificationScopes: uniqueStrings(allTests.map(testScope)),
+    },
+  };
+}
+
+function coverageForRequirement(
+  result: ExtractionResult,
+  manifestResults: readonly ExtractionResult[],
+  entities: ReadonlyMap<string, ExtractedEntity>,
+): RequirementCoverage {
+  const resultsById = new Map(
+    manifestResults.map((manifestResult) => [
+      manifestResult.entity.id,
+      manifestResult,
+    ]),
+  );
+  const scenarios = outgoingTargets({
+    result,
+    relationshipType: "specified_by",
+    type: "scenario",
+    entities,
+  });
+  const directTests = uniqueEntities([
+    ...outgoingTargets({
+      result,
+      relationshipType: "verified_by",
+      type: "test",
+      entities,
+    }),
+    ...outgoingTargets({
+      result,
+      relationshipType: "covered_by",
+      type: "test",
+      entities,
+    }),
+    ...incomingSources({
+      manifestResults,
+      targetId: result.entity.id,
+      relationshipType: "validates",
+      type: "test",
+    }),
+  ]);
+  const scenarioTests = uniqueEntities(
+    scenarios.flatMap((scenario) => {
+      const scenarioResult = resultsById.get(scenario.id);
+      return [
+        ...incomingSources({
+          manifestResults,
+          targetId: scenario.id,
+          relationshipType: "validates",
+          type: "test",
+        }),
+        ...(scenarioResult === undefined
+          ? []
+          : outgoingTargets({
+              result: scenarioResult,
+              relationshipType: "verified_by",
+              type: "test",
+              entities,
+            })),
+      ];
+    }),
+  );
+  return {
+    requirement: result.entity,
+    scenarioCount: scenarios.length,
+    directTests,
+    scenarioTests,
+  };
+}
+
+export function createCoverageDepthQualityDiagnostics(
+  manifestResults: readonly ExtractionResult[],
+): readonly QualityDiagnostic[] {
+  const entities = entitiesById(manifestResults);
+  return manifestResults
+    .filter((result) => result.entity.type === "req")
+    .flatMap((result) => {
+      const diagnostic = createDiagnostic(
+        coverageForRequirement(result, manifestResults, entities),
+      );
+      return diagnostic === undefined ? [] : [diagnostic];
+    })
+    .toSorted((left, right) =>
+      (left.entityId ?? "").localeCompare(right.entityId ?? ""),
+    );
+}

package/src/public/impact/diagnostics.ts

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import {
+  type ExtractedSymbol,
+  extractSymbolsFromStagedFile,
+} from "../../traceability/symbol-extract.js";
+import {
+  getBehavioralSymbolNames,
+  getNonBehavioralSymbolNames,
+  isAllowedGranularityReason,
+  isTraceabilityRelationshipType,
+} from "../symbol-granularity.js";
+import type {
+  QualityDiagnostic,
+  SemanticReviewDiagnosticsOptions,
+  SymbolGranularityDiagnosticsOptions,
+} from "./types.js";
+
+function isNarrowerSymbol(
+  manifestSymbolName: string,
+  candidate: ExtractedSymbol,
+  sourceSymbols: readonly ExtractedSymbol[],
+): boolean {
+  if (candidate.name === manifestSymbolName) return false;
+  if (candidate.name.startsWith(`${manifestSymbolName}.`)) return true;
+  return !sourceSymbols.some((symbol) => symbol.name === manifestSymbolName);
+}
+
+function hasTraceabilityRelationship(result: ExtractionResult): boolean {
+  return result.relationships.some((relationship) =>
+    isTraceabilityRelationshipType(relationship.type),
+  );
+}
+
+function hasValidGranularityReason(result: ExtractionResult): boolean {
+  return isAllowedGranularityReason(result.entity.granularity_reason);
+}
+
+function readSourceSymbols(
+  sourceFile: string,
+  sourceContentByFile: ReadonlyMap<string, string> | undefined,
+  workspaceRoot: string,
+): readonly ExtractedSymbol[] {
+  const stagedContent = sourceContentByFile?.get(sourceFile);
+  if (stagedContent !== undefined) {
+    return extractSymbolsFromStagedFile({
+      path: sourceFile,
+      status: "M",
+      hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+      content: stagedContent,
+    });
+  }
+
+  const absolutePath = path.isAbsolute(sourceFile)
+    ? sourceFile
+    : path.resolve(workspaceRoot, sourceFile);
+  if (!existsSync(absolutePath)) return [];
+
+  return extractSymbolsFromStagedFile({
+    path: sourceFile,
+    status: "M",
+    hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+    content: readFileSync(absolutePath, "utf8"),
+  });
+}
+
+function getGranularSymbolsForSourceFile(
+  sourceFile: string,
+  options: SymbolGranularityDiagnosticsOptions,
+): {
+  readonly candidateSymbols: readonly ExtractedSymbol[];
+  readonly sourceSymbols: readonly ExtractedSymbol[];
+} {
+  const sourceSymbols = readSourceSymbols(
+    sourceFile,
+    options.sourceContentByFile,
+    options.workspaceRoot ?? process.cwd(),
+  );
+  const changedSymbols = options.symbolsByFile.get(sourceFile);
+
+  return {
+    candidateSymbols: changedSymbols ?? sourceSymbols,
+    sourceSymbols:
+      sourceSymbols.length > 0 ? sourceSymbols : (changedSymbols ?? []),
+  };
+}
+
+function formatRelationshipTargets(symbol: ExtractedSymbol): string {
+  const targets = [
+    ...new Set(
+      (symbol.relationships ?? [])
+        .filter((relationship) =>
+          isTraceabilityRelationshipType(relationship.type),
+        )
+        .map((relationship) => relationship.to),
+    ),
+  ].sort();
+
+  return targets.length > 0 ? targets.join(", ") : "linked requirements/tests";
+}
+
+function isChangedBehavioralReviewCandidate(symbol: ExtractedSymbol): boolean {
+  if (symbol.role !== "behavioral") return false;
+  if (symbol.kind === "class") return false;
+  return symbol.hunkRanges.length > 0;
+}
+
+export function createSymbolGranularityDiagnostics(
+  options: SymbolGranularityDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  const diagnostics: KibiImpactDiagnostic[] = [];
+
+  for (const result of options.manifestResults) {
+    if (
+      options.activeEntityIds !== undefined &&
+      !options.activeEntityIds.has(result.entity.id)
+    ) {
+      continue;
+    }
+    if (!result.sourceFile) continue;
+    if (!hasTraceabilityRelationship(result)) continue;
+    if (hasValidGranularityReason(result)) continue;
+
+    const { candidateSymbols, sourceSymbols } = getGranularSymbolsForSourceFile(
+      result.sourceFile,
+      options,
+    );
+    const narrowerSymbols = candidateSymbols.filter((symbol) =>
+      isNarrowerSymbol(result.entity.title, symbol, sourceSymbols),
+    );
+    if (narrowerSymbols.length === 0) continue;
+
+    const behavioralNames = getBehavioralSymbolNames(narrowerSymbols);
+    if (behavioralNames.length === 0) continue;
+
+    const nonBehavioralNames = getNonBehavioralSymbolNames(narrowerSymbols);
+    const ignoredSymbolsSuggestion =
+      nonBehavioralNames.length > 0
+        ? ` Non-behavioral symbols ignored for this decision: ${nonBehavioralNames.join(
+            ", ",
+          )}.`
+        : "";
+
+    diagnostics.push({
+      id: "symbol_granularity_violation",
+      severity: "error",
+      blocking: true,
+      category: "symbol",
+      files: [result.entity.source, result.sourceFile],
+      docs: ["docs/symbol-traceability-taxonomy.md"],
+      message: `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`,
+      suggestion: `Move ownership/coverage/test relationships to the narrow behavioral symbol, add a manifest behavioral anchor, or add granularity_reason with config-artifact, module-level-behavior, extractor-miss, or legacy-link when the coarse symbol is intentional.${ignoredSymbolsSuggestion}`,
+    });
+  }
+
+  return diagnostics;
+}
+
+export function createSemanticReviewDiagnostics(
+  options: SemanticReviewDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  const diagnostics: KibiImpactDiagnostic[] = [];
+
+  for (const symbols of options.symbolsByFile.values()) {
+    for (const symbol of symbols) {
+      if (!isChangedBehavioralReviewCandidate(symbol)) continue;
+
+      const linkedTargets = formatRelationshipTargets(symbol);
+      diagnostics.push({
+        id: "symbol_semantic_review_needed",
+        severity: "warning",
+        blocking: false,
+        category: "symbol",
+        files: [symbol.location.file],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
+        suggestion: `Use kb_search and kb_query for ${symbol.location.file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export function hasBlockingImpactDiagnostics(
+  diagnostics: readonly KibiImpactDiagnostic[],
+): boolean {
+  return hasBlockingQualityDiagnostics(diagnostics);
+}
+
+export function hasBlockingQualityDiagnostics(
+  diagnostics: readonly QualityDiagnostic[],
+): boolean {
+  return diagnostics.some(
+    (diagnostic) => diagnostic.blocking || diagnostic.severity === "error",
+  );
+}

package/src/public/impact/diff-meaning.ts

@@ -0,0 +1,121 @@
+function normalizeDiffContent(line: string): string {
+  let normalized = "";
+  let quote: '"' | "'" | "`" | null = null;
+  let escaped = false;
+
+  for (const character of line.slice(1)) {
+    if (quote !== null) {
+      normalized += character;
+
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (character === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (character === quote) quote = null;
+      continue;
+    }
+
+    if (character === '"' || character === "'" || character === "`") {
+      quote = character;
+      normalized += character;
+      continue;
+    }
+
+    if (!/\s/.test(character)) normalized += character;
+  }
+
+  return normalized;
+}
+
+function removeSyntacticTrailingCommas(content: string): string {
+  let normalized = "";
+  let quote: '"' | "'" | "`" | null = null;
+  let escaped = false;
+
+  for (let index = 0; index < content.length; index += 1) {
+    const character = content[index];
+    if (character === undefined) continue;
+
+    if (quote !== null) {
+      normalized += character;
+
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (character === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (character === quote) quote = null;
+      continue;
+    }
+
+    if (character === '"' || character === "'" || character === "`") {
+      quote = character;
+      normalized += character;
+      continue;
+    }
+
+    const nextCharacter = content[index + 1];
+    if (
+      character === "," &&
+      (nextCharacter === ")" || nextCharacter === "]" || nextCharacter === "}")
+    ) {
+      continue;
+    }
+
+    normalized += character;
+  }
+
+  return normalized;
+}
+
+function hasMeaningfulDiffHunk(diffLines: readonly string[]): boolean {
+  let removedContent = "";
+  let addedContent = "";
+
+  for (const line of diffLines) {
+    if (line.startsWith("-") && !line.startsWith("---")) {
+      removedContent += normalizeDiffContent(line);
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      addedContent += normalizeDiffContent(line);
+    }
+  }
+
+  const normalizedRemovedContent =
+    removeSyntacticTrailingCommas(removedContent);
+  const normalizedAddedContent = removeSyntacticTrailingCommas(addedContent);
+
+  if (
+    normalizedRemovedContent.length === 0 &&
+    normalizedAddedContent.length === 0
+  ) {
+    return false;
+  }
+  return normalizedRemovedContent !== normalizedAddedContent;
+}
+
+// implements REQ-cli-staged-impact-enforcement
+export function hasMeaningfulSourceDiff(diffText: string): boolean {
+  const hunkLines: string[] = [];
+
+  for (const line of diffText.split(/\r?\n/)) {
+    if (line.startsWith("@@")) {
+      if (hasMeaningfulDiffHunk(hunkLines)) return true;
+      hunkLines.length = 0;
+      continue;
+    }
+    if (hunkLines.length > 0 || line.startsWith("+") || line.startsWith("-")) {
+      hunkLines.push(line);
+    }
+  }
+
+  return hasMeaningfulDiffHunk(hunkLines);
+}