kibi-cli 0.12.8 → 0.14.0

package/src/public/impact/requirement-quality.ts

@@ -0,0 +1,282 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import type { RequirementQualityDiagnosticsOptions } from "./types.js";
+
+const CURRENT_REQUIREMENT_STATUSES: ReadonlySet<string> = new Set([
+  "open",
+  "in_progress",
+  "active",
+  "accepted",
+]);
+
+const TEST_LIKE_REQUIREMENT_STATUSES: ReadonlySet<string> = new Set([
+  "passing",
+  "failing",
+  "skipped",
+  "pending",
+]);
+
+const STRICT_RELATIONSHIP_TYPES: ReadonlySet<string> = new Set([
+  "constrains",
+  "requires_property",
+  "requires_predicate",
+]);
+
+const BROAD_REQUIREMENT_THRESHOLDS = {
+  implementingSymbols: 8,
+  scenarios: 6,
+  tests: 8,
+  dependentRequirements: 5,
+} as const;
+
+const NORMATIVE_INDICATOR_PATTERNS: readonly [string, RegExp][] = [
+  ["must", /\bmust\b/i],
+  ["only", /\bonly\b/i],
+  ["never", /\bnever\b/i],
+  ["limit", /\blimits?\b/i],
+  ["minimum", /\bminimum\b/i],
+  ["maximum", /\bmaximum\b/i],
+  ["at least", /\bat\s+least\b/i],
+  ["at most", /\bat\s+most\b/i],
+];
+
+type RequirementFanout = {
+  readonly implementingSymbolIds: readonly string[];
+  readonly scenarioIds: readonly string[];
+  readonly testIds: readonly string[];
+  readonly dependentRequirementIds: readonly string[];
+};
+
+function isRequirement(result: ExtractionResult): boolean {
+  return result.entity.type === "req";
+}
+
+function isCurrentRequirement(result: ExtractionResult): boolean {
+  return (
+    isRequirement(result) &&
+    CURRENT_REQUIREMENT_STATUSES.has(result.entity.status)
+  );
+}
+
+function sortedUnique(values: readonly string[]): readonly string[] {
+  return [...new Set(values)].sort();
+}
+
+function entityTypeById(
+  results: readonly ExtractionResult[],
+): ReadonlyMap<string, string> {
+  const types = new Map<string, string>();
+  for (const result of results) {
+    types.set(result.entity.id, result.entity.type);
+  }
+  return types;
+}
+
+function targetHasType(
+  targetId: string,
+  type: string,
+  typesByEntityId: ReadonlyMap<string, string>,
+): boolean {
+  const targetType = typesByEntityId.get(targetId);
+  return targetType === undefined || targetType === type;
+}
+
+function collectFanout(
+  requirementId: string,
+  results: readonly ExtractionResult[],
+  typesByEntityId: ReadonlyMap<string, string>,
+): RequirementFanout {
+  const implementingSymbolIds: string[] = [];
+  const scenarioIds: string[] = [];
+  const testIds: string[] = [];
+  const dependentRequirementIds: string[] = [];
+
+  for (const result of results) {
+    for (const relationship of result.relationships) {
+      if (
+        relationship.type === "implements" &&
+        relationship.to === requirementId
+      ) {
+        implementingSymbolIds.push(result.entity.id);
+      }
+      if (
+        result.entity.id === requirementId &&
+        relationship.type === "specified_by" &&
+        targetHasType(relationship.to, "scenario", typesByEntityId)
+      ) {
+        scenarioIds.push(relationship.to);
+      }
+      if (
+        result.entity.id === requirementId &&
+        (relationship.type === "verified_by" ||
+          relationship.type === "covered_by") &&
+        targetHasType(relationship.to, "test", typesByEntityId)
+      ) {
+        testIds.push(relationship.to);
+      }
+      if (relationship.type === "depends_on") {
+        if (
+          result.entity.id === requirementId &&
+          targetHasType(relationship.to, "req", typesByEntityId)
+        ) {
+          dependentRequirementIds.push(relationship.to);
+        }
+        if (relationship.to === requirementId && result.entity.type === "req") {
+          dependentRequirementIds.push(result.entity.id);
+        }
+      }
+    }
+  }
+
+  return {
+    implementingSymbolIds: sortedUnique(implementingSymbolIds),
+    scenarioIds: sortedUnique(scenarioIds),
+    testIds: sortedUnique(testIds),
+    dependentRequirementIds: sortedUnique(dependentRequirementIds),
+  };
+}
+
+function exceedsBroadThreshold(fanout: RequirementFanout): boolean {
+  return (
+    fanout.implementingSymbolIds.length >
+      BROAD_REQUIREMENT_THRESHOLDS.implementingSymbols ||
+    fanout.scenarioIds.length > BROAD_REQUIREMENT_THRESHOLDS.scenarios ||
+    fanout.testIds.length > BROAD_REQUIREMENT_THRESHOLDS.tests ||
+    fanout.dependentRequirementIds.length >
+      BROAD_REQUIREMENT_THRESHOLDS.dependentRequirements
+  );
+}
+
+function isUmbrellaRequirement(result: ExtractionResult): boolean {
+  const tags = result.entity.tags ?? [];
+  return tags.some((tag) => tag === "umbrella" || tag === "epic");
+}
+
+function createBroadRequirementDiagnostics(
+  results: readonly ExtractionResult[],
+): readonly KibiImpactDiagnostic[] {
+  const typesByEntityId = entityTypeById(results);
+  return results.flatMap((result) => {
+    if (!isCurrentRequirement(result)) return [];
+    const fanout = collectFanout(result.entity.id, results, typesByEntityId);
+    if (!exceedsBroadThreshold(fanout)) return [];
+    if (isUmbrellaRequirement(result)) return [];
+
+    return [
+      {
+        id: "broad_requirement_review",
+        severity: "review",
+        blocking: false,
+        category: "requirement",
+        entityId: result.entity.id,
+        source: result.entity.source,
+        files: [result.entity.source],
+        docs: ["docs/entity-schema.md"],
+        message: `Requirement ${result.entity.id} has broad fanout that exceeds requirement review thresholds.`,
+        suggestion:
+          "Split this into smaller behavioral requirements, or keep an explicit umbrella/epic tag when broad ownership is intentional.",
+        evidence: {
+          implementingSymbolIds: fanout.implementingSymbolIds,
+          implementingSymbolCount: fanout.implementingSymbolIds.length,
+          implementingSymbolThreshold:
+            BROAD_REQUIREMENT_THRESHOLDS.implementingSymbols,
+          scenarioIds: fanout.scenarioIds,
+          scenarioCount: fanout.scenarioIds.length,
+          scenarioThreshold: BROAD_REQUIREMENT_THRESHOLDS.scenarios,
+          testIds: fanout.testIds,
+          testCount: fanout.testIds.length,
+          testThreshold: BROAD_REQUIREMENT_THRESHOLDS.tests,
+          dependentRequirementIds: fanout.dependentRequirementIds,
+          dependentRequirementCount: fanout.dependentRequirementIds.length,
+          dependentRequirementThreshold:
+            BROAD_REQUIREMENT_THRESHOLDS.dependentRequirements,
+        },
+      },
+    ];
+  });
+}
+
+function createRequirementStatusDiagnostics(
+  results: readonly ExtractionResult[],
+): readonly KibiImpactDiagnostic[] {
+  return results.flatMap((result) => {
+    if (!isRequirement(result)) return [];
+    if (!TEST_LIKE_REQUIREMENT_STATUSES.has(result.entity.status)) return [];
+
+    return [
+      {
+        id: "requirement_status_review",
+        severity: "review",
+        blocking: false,
+        category: "status",
+        entityId: result.entity.id,
+        source: result.entity.source,
+        files: [result.entity.source],
+        docs: ["docs/entity-schema.md"],
+        message: `Requirement ${result.entity.id} uses test-like status ${result.entity.status}.`,
+        suggestion:
+          "Use requirement lifecycle statuses such as open, in_progress, active, accepted, closed, deprecated, or superseded; keep passing/failing statuses on test entities.",
+        evidence: { status: result.entity.status },
+      },
+    ];
+  });
+}
+
+function strictRelationshipTypes(result: ExtractionResult): readonly string[] {
+  return sortedUnique(
+    result.relationships
+      .filter((relationship) =>
+        STRICT_RELATIONSHIP_TYPES.has(relationship.type),
+      )
+      .map((relationship) => relationship.type),
+  );
+}
+
+function matchedNormativeIndicators(text: string): readonly string[] {
+  return NORMATIVE_INDICATOR_PATTERNS.filter((entry) =>
+    entry[1].test(text),
+  ).map((entry) => entry[0]);
+}
+
+function createStrictFactModelingDiagnostics(
+  options: RequirementQualityDiagnosticsOptions,
+): readonly KibiImpactDiagnostic[] {
+  return options.manifestResults.flatMap((result) => {
+    if (!isCurrentRequirement(result)) return [];
+    if (options.hardViolationEntityIds?.has(result.entity.id)) return [];
+    const relationshipTypes = strictRelationshipTypes(result);
+    if (relationshipTypes.length > 0) return [];
+    const indicators = matchedNormativeIndicators(result.entity.title);
+    if (indicators.length === 0) return [];
+
+    return [
+      {
+        id: "strict_fact_modeling_review",
+        severity: "review",
+        blocking: false,
+        category: "fact",
+        entityId: result.entity.id,
+        source: result.entity.source,
+        files: [result.entity.source],
+        docs: ["docs/modeling-cheatsheet.md", "docs/error-reference.md"],
+        message: `Requirement ${result.entity.id} contains normative prose but has no strict fact or predicate relationship.`,
+        suggestion:
+          "Use kb_model_requirement for strict property facts, or kb_suggest_predicates when the claim fits a predicate schema.",
+        evidence: {
+          matchedIndicators: indicators,
+          strictRelationshipTypes: relationshipTypes,
+        },
+      },
+    ];
+  });
+}
+
+export function createRequirementQualityDiagnostics(
+  options: RequirementQualityDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  return [
+    ...createBroadRequirementDiagnostics(options.manifestResults),
+    ...createRequirementStatusDiagnostics(options.manifestResults),
+    ...createStrictFactModelingDiagnostics(options),
+  ];
+}

package/src/public/impact/source-changes.ts

@@ -0,0 +1,180 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import type { HunkRange } from "../../traceability/git-staged.js";
+import {
+  getStagedFiles,
+  parseHunksFromDiff,
+} from "../../traceability/git-staged.js";
+import { hasMeaningfulSourceDiff } from "./diff-meaning.js";
+import type { ChangedFileImpactOptions, SourceChange } from "./types.js";
+
+const SOURCE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mts",
+  ".cts",
+  ".mjs",
+  ".cjs",
+]);
+
+function isSupportedSourcePath(filePath: string): boolean {
+  return SOURCE_EXTENSIONS.has(path.extname(filePath));
+}
+
+export function normalizeSourceFile(
+  workspaceRoot: string,
+  sourceFile: string,
+): string {
+  const relativePath = path.isAbsolute(sourceFile)
+    ? path.relative(workspaceRoot, sourceFile)
+    : sourceFile;
+  return relativePath.split(path.sep).join("/");
+}
+
+export function uniqueSorted(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort();
+}
+
+function escapeGitPath(filePath: string): string {
+  return filePath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function runGit(workspaceRoot: string, command: string): string {
+  return execSync(command, { cwd: workspaceRoot, encoding: "utf8" });
+}
+
+function readWorkingTreeSource(
+  workspaceRoot: string,
+  sourceFile: string,
+): string | null {
+  const absolutePath = path.resolve(workspaceRoot, sourceFile);
+  if (!existsSync(absolutePath)) return null;
+  return readFileSync(absolutePath, "utf8");
+}
+
+function fullFileHunk(content: string): HunkRange[] {
+  return [{ start: 1, end: Math.max(1, content.split(/\r?\n/).length) }];
+}
+
+function getWorkingTreeDiffSourceFiles(workspaceRoot: string): string[] {
+  try {
+    return uniqueSorted(
+      runGit(workspaceRoot, "git diff --name-only --diff-filter=ACMR")
+        .split(/\r?\n/)
+        .map((filePath) => normalizeSourceFile(workspaceRoot, filePath.trim()))
+        .filter((filePath) => filePath.length > 0)
+        .filter(isSupportedSourcePath),
+    );
+  } catch {
+    return [];
+  }
+}
+
+function getWorkingTreeHunks(
+  workspaceRoot: string,
+  sourceFile: string,
+): HunkRange[] {
+  try {
+    const diffText = runGit(
+      workspaceRoot,
+      `git diff -U0 -- "${escapeGitPath(sourceFile)}"`,
+    );
+    return parseHunksFromDiff(diffText);
+  } catch {
+    return [];
+  }
+}
+
+function getStagedSourceChanges(
+  workspaceRoot: string,
+  sourceFileFilter: ReadonlySet<string>,
+): SourceChange[] {
+  const stagedFiles = getStagedFiles((command, options) =>
+    execSync(command, { ...options, cwd: workspaceRoot }),
+  );
+
+  return stagedFiles
+    .filter((file) => isSupportedSourcePath(file.path))
+    .filter(
+      (file) => sourceFileFilter.size === 0 || sourceFileFilter.has(file.path),
+    )
+    .flatMap((file): SourceChange[] => {
+      if (file.content === undefined || file.hunkRanges.length === 0) return [];
+      if (
+        file.diffText !== undefined &&
+        !hasMeaningfulSourceDiff(file.diffText)
+      ) {
+        return [];
+      }
+      return [
+        {
+          file: file.path,
+          status: file.status,
+          hunkRanges: file.hunkRanges,
+          content: file.content,
+        },
+      ];
+    });
+}
+
+function getWorkingTreeSourceChanges(
+  workspaceRoot: string,
+  sourceFileFilter: ReadonlySet<string>,
+): SourceChange[] {
+  const sourceFiles =
+    sourceFileFilter.size > 0
+      ? [...sourceFileFilter]
+      : getWorkingTreeDiffSourceFiles(workspaceRoot);
+
+  return sourceFiles.flatMap((sourceFile): SourceChange[] => {
+    const content = readWorkingTreeSource(workspaceRoot, sourceFile);
+    if (content === null) return [];
+    const diffText = runGit(
+      workspaceRoot,
+      `git diff -U0 -- "${escapeGitPath(sourceFile)}"`,
+    );
+    if (!hasMeaningfulSourceDiff(diffText)) return [];
+    const hunkRanges = getWorkingTreeHunks(workspaceRoot, sourceFile);
+    if (hunkRanges.length === 0) return [];
+    return [{ file: sourceFile, status: "M", hunkRanges, content }];
+  });
+}
+
+function getExplicitSourceChanges(
+  workspaceRoot: string,
+  sourceFileFilter: ReadonlySet<string>,
+): SourceChange[] {
+  return [...sourceFileFilter].flatMap((sourceFile): SourceChange[] => {
+    const content = readWorkingTreeSource(workspaceRoot, sourceFile);
+    if (content === null) return [];
+    return [
+      {
+        file: sourceFile,
+        status: "M",
+        hunkRanges: fullFileHunk(content),
+        content,
+      },
+    ];
+  });
+}
+
+export function collectSourceChanges(
+  options: ChangedFileImpactOptions,
+): SourceChange[] {
+  const workspaceRoot = path.resolve(options.workspaceRoot);
+  const sourceFileFilter = new Set(
+    (options.sourceFiles ?? [])
+      .map((sourceFile) => normalizeSourceFile(workspaceRoot, sourceFile))
+      .filter(isSupportedSourcePath),
+  );
+
+  if (options.staged)
+    return getStagedSourceChanges(workspaceRoot, sourceFileFilter);
+  if (options.includeWorkingTreeDiff) {
+    return getWorkingTreeSourceChanges(workspaceRoot, sourceFileFilter);
+  }
+  return getExplicitSourceChanges(workspaceRoot, sourceFileFilter);
+}

package/src/public/impact/summaries.ts

@@ -0,0 +1,100 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
+import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
+import { uniqueSorted } from "./source-changes.js";
+import type {
+  ImpactExtractedSymbol,
+  ImpactLinkedEntity,
+  SymbolsByFile,
+} from "./types.js";
+
+function linkedEntityIdsFor(symbol: ExtractedSymbol): string[] {
+  return uniqueSorted(
+    (symbol.relationships ?? [])
+      .filter((relationship) =>
+        isTraceabilityRelationshipType(relationship.type),
+      )
+      .map((relationship) => relationship.to),
+  );
+}
+
+export function formatExtractedSymbols(
+  symbolsByFile: SymbolsByFile,
+): ImpactExtractedSymbol[] {
+  return [...symbolsByFile.values()]
+    .flatMap((symbols) => [...symbols])
+    .map((symbol) => ({
+      id: symbol.id,
+      name: symbol.name,
+      kind: symbol.kind,
+      role: symbol.role,
+      location: symbol.location,
+      hunkRanges: symbol.hunkRanges,
+      linkedEntityIds: linkedEntityIdsFor(symbol),
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function collectLinkedEntities(
+  symbolsByFile: SymbolsByFile,
+  manifestResults: readonly ExtractionResult[],
+  activeSourceFiles: ReadonlySet<string>,
+): ImpactLinkedEntity[] {
+  const linkedEntities = new Map<string, ImpactLinkedEntity>();
+  const add = (entity: ImpactLinkedEntity): void => {
+    linkedEntities.set(
+      `${entity.sourceSymbolId}:${entity.relationshipType}:${entity.id}`,
+      entity,
+    );
+  };
+
+  for (const symbols of symbolsByFile.values()) {
+    for (const symbol of symbols) {
+      for (const relationship of symbol.relationships ?? []) {
+        if (!isTraceabilityRelationshipType(relationship.type)) continue;
+        add({
+          id: relationship.to,
+          relationshipType: relationship.type,
+          sourceSymbolId: symbol.id,
+          sourceSymbolName: symbol.name,
+        });
+      }
+    }
+  }
+
+  for (const result of manifestResults) {
+    if (
+      result.sourceFile === undefined ||
+      !activeSourceFiles.has(result.sourceFile)
+    ) {
+      continue;
+    }
+    for (const relationship of result.relationships) {
+      if (!isTraceabilityRelationshipType(relationship.type)) continue;
+      add({
+        id: relationship.to,
+        relationshipType: relationship.type,
+        sourceSymbolId: result.entity.id,
+        sourceSymbolName: result.entity.title,
+      });
+    }
+  }
+
+  return [...linkedEntities.values()].sort((left, right) =>
+    left.id.localeCompare(right.id),
+  );
+}
+
+export function buildNextActions(sourceFiles: readonly string[]): string[] {
+  if (sourceFiles.length === 0) return [];
+
+  return [
+    `kb_search({ query: "${sourceFiles.join(" ")}" }) to discover requirements/tests that may describe the changed behavior.`,
+    ...sourceFiles.map(
+      (sourceFile) =>
+        `kb_query({ sourceFile: "${sourceFile}" }) to inspect exact source-linked Kibi entities before deciding whether requirements/tests need updates.`,
+    ),
+    "Update narrower symbols, requirements, tests, or strict facts when diagnostics show broad or stale modeling.",
+    "rerun kb_check with the same sourceFiles/impact options after Kibi updates.",
+  ];
+}