kibi-cli 0.12.8 → 0.16.1

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

@@ -0,0 +1,230 @@
+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: Pick<PrologProcess, "query">;
+  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 logicClaims = optionalStringArrayField(entity, "logic_claims");
+  if (logicClaims !== undefined) extracted.logic_claims = logicClaims;
+  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" ||
+    factKind === "predicate_schema" ||
+    factKind === "predicate"
+  ) {
+    extracted.fact_kind = factKind;
+  }
+  const claimKey = optionalStringField(entity, "claim_key");
+  if (claimKey !== undefined) extracted.claim_key = claimKey;
+  const claimText = optionalStringField(entity, "claim_text");
+  if (claimText !== undefined) extracted.claim_text = claimText;
+  const predicateName = optionalStringField(entity, "predicate_name");
+  if (predicateName !== undefined) extracted.predicate_name = predicateName;
+  const predicateNamespace = optionalStringField(entity, "predicate_namespace");
+  if (predicateNamespace !== undefined) {
+    extracted.predicate_namespace = predicateNamespace;
+  }
+  const predicateArity = optionalNumberField(entity, "predicate_arity");
+  if (predicateArity !== undefined) extracted.predicate_arity = predicateArity;
+  for (const field of [
+    "argument_names",
+    "argument_types",
+    "argument_descriptions",
+    "aliases",
+    "examples",
+    "predicate_args",
+  ] as const) {
+    const values = optionalStringArrayField(entity, field);
+    if (values !== undefined) extracted[field] = values;
+  }
+  return extracted;
+}
+
+function sourceFileFor(entity: Record<string, unknown>): string | undefined {
+  return (
+    optionalStringField(entity, "sourceFile") ??
+    optionalStringField(entity, "source_file")
+  );
+}
+
+async function loadKbExtractionResults(
+  prolog: Pick<PrologProcess, "query">,
+): 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;
+}

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

@@ -0,0 +1,262 @@
+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;
+
+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 createLogicalCoverageDiagnostics(
+  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 ((result.entity.logic_claims?.length ?? 0) > 0) return [];
+
+    return [
+      {
+        id: "logical_coverage_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: `Current requirement ${result.entity.id} has no atomic logic_claims manifest, so prose and existing fact links cannot prove complete logical coverage.`,
+        suggestion:
+          "Call kb_semantic_advisor with the complete requirement prose and atomic clauses, ground each returned claim key through kb_model_requirement or kb_suggest_predicates, and persist all keys in logic_claims.",
+        evidence: {
+          strictRelationshipTypes: relationshipTypes,
+        },
+      },
+    ];
+  });
+}
+
+export function createRequirementQualityDiagnostics(
+  options: RequirementQualityDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  return [
+    ...createBroadRequirementDiagnostics(options.manifestResults),
+    ...createRequirementStatusDiagnostics(options.manifestResults),
+    ...createLogicalCoverageDiagnostics(options),
+  ];
+}