kibi-cli 0.12.8 → 0.14.0

package/src/public/impact/diagnostics.ts

@@ -0,0 +1,192 @@
+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 ExtractedSymbol[] {
+  return (
+    options.symbolsByFile.get(sourceFile) ??
+    readSourceSymbols(
+      sourceFile,
+      options.sourceContentByFile,
+      options.workspaceRoot ?? process.cwd(),
+    )
+  );
+}
+
+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 granularSymbols = getGranularSymbolsForSourceFile(
+      result.sourceFile,
+      options,
+    );
+    const narrowerSymbols = granularSymbols.filter((symbol) =>
+      isNarrowerSymbol(result.entity.title, symbol, granularSymbols),
+    );
+    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);
+}

package/src/public/impact/full-kb-quality.ts

@@ -0,0 +1,203 @@
+import type {
+  ExtractedEntity,
+  ExtractionResult,
+} from "../../extractors/markdown.js";
+import type { PrologProcess } from "../../prolog.js";
+import {
+  parseEntityFromList,
+  parseListOfLists,
+  parseTriples,
+} from "../../prolog/codec.js";
+import { createCoverageDepthQualityDiagnostics } from "./coverage-depth-quality.js";
+import { createRequirementQualityDiagnostics } from "./requirement-quality.js";
+import { createSymbolQualityDiagnostics } from "./symbol-quality.js";
+import type { QualityDiagnostic } from "./types.js";
+
+const RELATIONSHIP_TYPES = [
+  "depends_on",
+  "executable_for",
+  "specified_by",
+  "verified_by",
+  "validates",
+  "implements",
+  "covered_by",
+  "constrained_by",
+  "constrains",
+  "requires_property",
+  "requires_predicate",
+  "guards",
+  "publishes",
+  "consumes",
+  "supersedes",
+  "relates_to",
+] as const;
+
+type FullKbQualityDiagnosticsOptions = {
+  readonly prolog: PrologProcess;
+  readonly hardViolationEntityIds?: ReadonlySet<string>;
+  readonly maxDiagnostics?: number;
+};
+
+function stringField(entity: Record<string, unknown>, key: string): string {
+  const value = entity[key];
+  return typeof value === "string" ? value : "";
+}
+
+function optionalStringField(
+  entity: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = entity[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optionalNumberField(
+  entity: Record<string, unknown>,
+  key: string,
+): number | undefined {
+  const value = entity[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+function optionalStringArrayField(
+  entity: Record<string, unknown>,
+  key: string,
+): string[] | undefined {
+  const value = entity[key];
+  if (!Array.isArray(value)) return undefined;
+  return value.map((item) => String(item));
+}
+
+function toExtractedEntity(entity: Record<string, unknown>): ExtractedEntity {
+  const extracted: ExtractedEntity = {
+    id: stringField(entity, "id"),
+    type: stringField(entity, "type"),
+    title: stringField(entity, "title"),
+    status: stringField(entity, "status"),
+    created_at: stringField(entity, "created_at"),
+    updated_at: stringField(entity, "updated_at"),
+    source: stringField(entity, "source"),
+  };
+  const tags = optionalStringArrayField(entity, "tags");
+  if (tags !== undefined) extracted.tags = tags;
+  const owner = optionalStringField(entity, "owner");
+  if (owner !== undefined) extracted.owner = owner;
+  const priority = optionalStringField(entity, "priority");
+  if (priority !== undefined) extracted.priority = priority;
+  const severity = optionalStringField(entity, "severity");
+  if (severity !== undefined) extracted.severity = severity;
+  const textRef = optionalStringField(entity, "text_ref");
+  if (textRef !== undefined) extracted.text_ref = textRef;
+  const granularityReason = optionalStringField(entity, "granularity_reason");
+  if (granularityReason !== undefined) {
+    extracted.granularity_reason = granularityReason;
+  }
+  const symbolKind = optionalStringField(entity, "symbol_kind");
+  if (symbolKind !== undefined) extracted.symbol_kind = symbolKind;
+  const symbolRole = optionalStringField(entity, "symbol_role");
+  if (symbolRole !== undefined) extracted.symbol_role = symbolRole;
+  const verificationScope = optionalStringField(entity, "verification_scope");
+  if (
+    verificationScope === "unit" ||
+    verificationScope === "integration" ||
+    verificationScope === "end_to_end"
+  ) {
+    extracted.verification_scope = verificationScope;
+  }
+  const sourceLine = optionalNumberField(entity, "sourceLine");
+  if (sourceLine !== undefined) extracted.sourceLine = sourceLine;
+  const sourceColumn = optionalNumberField(entity, "sourceColumn");
+  if (sourceColumn !== undefined) extracted.sourceColumn = sourceColumn;
+  const sourceEndLine = optionalNumberField(entity, "sourceEndLine");
+  if (sourceEndLine !== undefined) extracted.sourceEndLine = sourceEndLine;
+  const sourceEndColumn = optionalNumberField(entity, "sourceEndColumn");
+  if (sourceEndColumn !== undefined)
+    extracted.sourceEndColumn = sourceEndColumn;
+  const factKind = optionalStringField(entity, "fact_kind");
+  if (
+    factKind === "subject" ||
+    factKind === "property_value" ||
+    factKind === "observation" ||
+    factKind === "meta"
+  ) {
+    extracted.fact_kind = factKind;
+  }
+  return extracted;
+}
+
+function sourceFileFor(entity: Record<string, unknown>): string | undefined {
+  return (
+    optionalStringField(entity, "sourceFile") ??
+    optionalStringField(entity, "source_file")
+  );
+}
+
+async function loadKbExtractionResults(
+  prolog: PrologProcess,
+): Promise<ExtractionResult[]> {
+  const entityResult = await prolog.query(
+    "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)",
+  );
+  const entities = entityResult.bindings.Results
+    ? parseListOfLists(entityResult.bindings.Results).map(parseEntityFromList)
+    : [];
+  const relationships = new Map<string, ExtractionResult["relationships"]>();
+
+  for (const relationshipType of RELATIONSHIP_TYPES) {
+    const relResult = await prolog.query(
+      `findall([From,To,'${relationshipType}'], kb_relationship(${relationshipType}, From, To), Rels)`,
+    );
+    const rows = relResult.bindings.Rels
+      ? parseTriples(relResult.bindings.Rels)
+      : [];
+    for (const [from, to, type] of rows) {
+      const current = relationships.get(from) ?? [];
+      current.push({ from, to, type });
+      relationships.set(from, current);
+    }
+  }
+
+  return entities.map((entity) => {
+    const result: ExtractionResult = {
+      entity: toExtractedEntity(entity),
+      relationships: relationships.get(stringField(entity, "id")) ?? [],
+    };
+    const sourceFile = sourceFileFor(entity);
+    if (sourceFile !== undefined) {
+      result.sourceFile = sourceFile;
+    }
+    return result;
+  });
+}
+
+function capDiagnostics(
+  diagnostics: readonly QualityDiagnostic[],
+  maxDiagnostics: number | undefined,
+): readonly QualityDiagnostic[] {
+  return maxDiagnostics !== undefined && maxDiagnostics >= 0
+    ? diagnostics.slice(0, maxDiagnostics)
+    : diagnostics;
+}
+
+export async function collectFullKbQualityDiagnostics(
+  options: FullKbQualityDiagnosticsOptions,
+): Promise<readonly QualityDiagnostic[]> {
+  const manifestResults = await loadKbExtractionResults(options.prolog);
+  const coverageDepthDiagnostics =
+    createCoverageDepthQualityDiagnostics(manifestResults);
+  const diagnostics = [
+    ...createRequirementQualityDiagnostics({
+      manifestResults,
+      ...(options.hardViolationEntityIds !== undefined
+        ? { hardViolationEntityIds: options.hardViolationEntityIds }
+        : {}),
+    }),
+    ...coverageDepthDiagnostics,
+    ...createSymbolQualityDiagnostics({
+      manifestResults,
+      symbolsByFile: new Map(),
+    }),
+  ];
+
+  return capDiagnostics(diagnostics, options.maxDiagnostics);
+}

package/src/public/impact/manifest.ts

@@ -0,0 +1,57 @@
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { extractFromManifest } from "../../extractors/manifest.js";
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { ManifestLookup } from "../../traceability/symbol-extract.js";
+import { loadConfig } from "../../utils/config.js";
+import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
+import { normalizeSourceFile } from "./source-changes.js";
+import type { TraceabilityRelationship } from "./types.js";
+
+function toTraceabilityRelationships(
+  relationships: ExtractionResult["relationships"],
+): TraceabilityRelationship[] {
+  return relationships
+    .filter((relationship) => isTraceabilityRelationshipType(relationship.type))
+    .map((relationship) => ({ type: relationship.type, to: relationship.to }));
+}
+
+export function readImpactManifestResults(
+  workspaceRoot: string,
+): readonly ExtractionResult[] {
+  const config = loadConfig(workspaceRoot);
+  const symbolsPath = config.paths.symbols;
+  if (!symbolsPath) return [];
+
+  const absolutePath = path.isAbsolute(symbolsPath)
+    ? symbolsPath
+    : path.resolve(workspaceRoot, symbolsPath);
+  if (!existsSync(absolutePath)) return [];
+
+  return extractFromManifest(absolutePath).map((result) => ({
+    entity: {
+      ...result.entity,
+      source: normalizeSourceFile(workspaceRoot, result.entity.source),
+    },
+    relationships: result.relationships,
+    ...(result.sourceFile !== undefined
+      ? { sourceFile: normalizeSourceFile(workspaceRoot, result.sourceFile) }
+      : {}),
+  }));
+}
+
+export function createImpactManifestLookup(
+  manifestResults: readonly ExtractionResult[],
+): ManifestLookup {
+  const manifestLookup: ManifestLookup = new Map();
+
+  for (const result of manifestResults) {
+    const sourceFile = result.sourceFile ?? result.entity.source;
+    manifestLookup.set(`${sourceFile}:${result.entity.title}`, {
+      id: result.entity.id,
+      relationships: toTraceabilityRelationships(result.relationships),
+    });
+  }
+
+  return manifestLookup;
+}