kibi-cli 0.12.8 → 0.16.1

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.",
+  ];
+}

package/src/public/impact/symbol-quality-model.ts

@@ -0,0 +1,171 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
+import {
+  type SymbolKind,
+  type SymbolRole,
+  getSymbolRole,
+} from "../symbol-granularity.js";
+import type { SymbolQualityDiagnosticsOptions } from "./types.js";
+
+export type SymbolMetadata = {
+  readonly result: ExtractionResult;
+  readonly id: string;
+  readonly title: string;
+  readonly sourceFile: string;
+  readonly source: string;
+  readonly kind: SymbolKind | "component" | "service" | "module" | "config";
+  readonly role: SymbolRole;
+  readonly requirementTargetIds: readonly string[];
+  readonly coordinateKey: string | null;
+};
+
+export const AGGREGATE_KINDS: ReadonlySet<string> = new Set([
+  "class",
+  "component",
+  "service",
+  "module",
+]);
+
+function isActiveSymbol(result: ExtractionResult): boolean {
+  return result.entity.type === "symbol" && result.entity.status === "active";
+}
+
+function getRequirementTargets(result: ExtractionResult): readonly string[] {
+  return [
+    ...new Set(
+      result.relationships
+        .filter(
+          (relationship) =>
+            relationship.type === "implements" &&
+            relationship.to.startsWith("REQ-"),
+        )
+        .map((relationship) => relationship.to),
+    ),
+  ].sort();
+}
+
+function inferKind(result: ExtractionResult): SymbolMetadata["kind"] {
+  const explicitKind = result.entity.symbol_kind;
+  if (
+    explicitKind === "component" ||
+    explicitKind === "service" ||
+    explicitKind === "module" ||
+    explicitKind === "config"
+  ) {
+    return explicitKind;
+  }
+  if (
+    explicitKind === "function" ||
+    explicitKind === "class" ||
+    explicitKind === "method" ||
+    explicitKind === "property" ||
+    explicitKind === "accessor" ||
+    explicitKind === "interface" ||
+    explicitKind === "type" ||
+    explicitKind === "variable" ||
+    explicitKind === "enum" ||
+    explicitKind === "unknown"
+  ) {
+    return explicitKind;
+  }
+
+  if (result.entity.title.endsWith("Component")) return "component";
+  if (result.entity.title.endsWith("Service")) return "service";
+  if (result.entity.title.endsWith("Module")) return "module";
+  if (result.entity.title.endsWith("Config")) return "config";
+  if (result.entity.title.includes(".")) return "method";
+  return "unknown";
+}
+
+function inferRole(
+  result: ExtractionResult,
+  kind: SymbolMetadata["kind"],
+): SymbolRole {
+  const explicitRole = result.entity.symbol_role;
+  if (
+    explicitRole === "behavioral" ||
+    explicitRole === "structural" ||
+    explicitRole === "type-shape" ||
+    explicitRole === "config" ||
+    explicitRole === "module" ||
+    explicitRole === "unknown"
+  ) {
+    return explicitRole;
+  }
+  if (kind === "component" || kind === "service") return "behavioral";
+  if (kind === "module") return "module";
+  if (kind === "config") return "config";
+  return getSymbolRole({ name: result.entity.title, kind });
+}
+
+function getCoordinateKey(result: ExtractionResult): string | null {
+  const { sourceLine, sourceColumn, sourceEndLine, sourceEndColumn } =
+    result.entity;
+  if (
+    sourceLine === undefined ||
+    sourceColumn === undefined ||
+    sourceEndLine === undefined ||
+    sourceEndColumn === undefined
+  ) {
+    return null;
+  }
+
+  return `${sourceLine}:${sourceColumn}:${sourceEndLine}:${sourceEndColumn}`;
+}
+
+export function collectSymbols(
+  options: SymbolQualityDiagnosticsOptions,
+): readonly SymbolMetadata[] {
+  return options.manifestResults
+    .filter((result) =>
+      options.activeEntityIds === undefined
+        ? isActiveSymbol(result)
+        : isActiveSymbol(result) &&
+          options.activeEntityIds.has(result.entity.id),
+    )
+    .flatMap((result) => {
+      if (result.sourceFile === undefined) return [];
+      const kind = inferKind(result);
+      return [
+        {
+          result,
+          id: result.entity.id,
+          title: result.entity.title,
+          sourceFile: result.sourceFile,
+          source: result.entity.source,
+          kind,
+          role: inferRole(result, kind),
+          requirementTargetIds: getRequirementTargets(result),
+          coordinateKey: getCoordinateKey(result),
+        },
+      ];
+    });
+}
+
+export function isModuleOrConfig(symbol: SymbolMetadata): boolean {
+  return symbol.role === "module" || symbol.role === "config";
+}
+
+export function narrowerManifestSymbols(
+  symbol: SymbolMetadata,
+  symbols: readonly SymbolMetadata[],
+): readonly SymbolMetadata[] {
+  return symbols.filter(
+    (candidate) =>
+      candidate.id !== symbol.id &&
+      candidate.sourceFile === symbol.sourceFile &&
+      candidate.title.startsWith(`${symbol.title}.`),
+  );
+}
+
+export function narrowerExtractedSymbols(
+  symbol: SymbolMetadata,
+  symbolsByFile: ReadonlyMap<string, readonly ExtractedSymbol[]>,
+): readonly ExtractedSymbol[] {
+  return (symbolsByFile.get(symbol.sourceFile) ?? []).filter(
+    (candidate) =>
+      candidate.name !== symbol.title &&
+      candidate.name.startsWith(`${symbol.title}.`) &&
+      candidate.role === "behavioral",
+  );
+}

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

@@ -0,0 +1,207 @@
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+import { isAllowedGranularityReason } from "../symbol-granularity.js";
+import {
+  AGGREGATE_KINDS,
+  type SymbolMetadata,
+  collectSymbols,
+  isModuleOrConfig,
+  narrowerExtractedSymbols,
+  narrowerManifestSymbols,
+} from "./symbol-quality-model.js";
+import type { SymbolQualityDiagnosticsOptions } from "./types.js";
+
+function thresholdFor(symbol: SymbolMetadata): number {
+  return AGGREGATE_KINDS.has(symbol.kind) ? 4 : 2;
+}
+
+function isMultiRequirementCandidate(symbol: SymbolMetadata): boolean {
+  if (isModuleOrConfig(symbol)) {
+    return !isAllowedGranularityReason(symbol.result.entity.granularity_reason);
+  }
+  return symbol.role === "behavioral";
+}
+
+function createMultiRequirementDiagnostics(
+  symbols: readonly SymbolMetadata[],
+): readonly KibiImpactDiagnostic[] {
+  return symbols.flatMap((symbol) => {
+    if (!isMultiRequirementCandidate(symbol)) return [];
+    const threshold = thresholdFor(symbol);
+    if (symbol.requirementTargetIds.length <= threshold) return [];
+
+    return [
+      {
+        id: "multi_requirement_symbol_review",
+        severity: "review",
+        blocking: false,
+        category: "symbol",
+        entityId: symbol.id,
+        source: symbol.source,
+        files: [symbol.source, symbol.sourceFile],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Symbol ${symbol.id} implements ${symbol.requirementTargetIds.length} requirements, above the ${threshold} target review threshold.`,
+        suggestion:
+          "Review whether this symbol owns multiple unrelated behaviors; move relationships to narrower behavioral symbols or add a valid granularity_reason when broad ownership is intentional.",
+        evidence: {
+          targetIds: symbol.requirementTargetIds,
+          targetCount: symbol.requirementTargetIds.length,
+          threshold,
+          symbolKind: symbol.kind,
+          symbolRole: symbol.role,
+          sourceFile: symbol.sourceFile,
+        },
+      },
+    ];
+  });
+}
+
+function hasDistinctCoordinates(symbols: readonly SymbolMetadata[]): boolean {
+  const coordinateKeys = symbols.map((symbol) => symbol.coordinateKey);
+  if (coordinateKeys.some((key) => key === null)) return false;
+  return new Set(coordinateKeys).size === coordinateKeys.length;
+}
+
+function createDuplicateCoordinateDiagnostics(
+  symbols: readonly SymbolMetadata[],
+): readonly KibiImpactDiagnostic[] {
+  const groups = Map.groupBy(
+    symbols,
+    (symbol) => `${symbol.sourceFile}\u0000${symbol.title}`,
+  );
+
+  return [...groups.values()].flatMap((group) => {
+    if (group.length < 2) return [];
+    if (hasDistinctCoordinates(group)) return [];
+    const first = group[0];
+    if (first === undefined) return [];
+    const candidateIds = group.map((symbol) => symbol.id).sort();
+
+    return [
+      {
+        id: "duplicate_symbol_coordinate_review",
+        severity: "review",
+        blocking: false,
+        category: "coordinate",
+        entityId: first.id,
+        source: first.source,
+        files: [first.source, first.sourceFile],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Symbols ${candidateIds.join(", ")} share title ${first.title} and source ${first.sourceFile} without distinct coordinate evidence.`,
+        suggestion:
+          "Refresh symbol coordinates or rename member-level manifest entries so duplicate modeled symbols are distinguishable after parsing.",
+        evidence: {
+          candidateIds,
+          title: first.title,
+          sourceFile: first.sourceFile,
+        },
+      },
+    ];
+  });
+}
+
+function requirementTagsById(
+  results: readonly ExtractionResult[],
+): ReadonlyMap<string, readonly string[]> {
+  const tagsById = new Map<string, readonly string[]>();
+  for (const result of results) {
+    if (result.entity.type !== "req") continue;
+    tagsById.set(result.entity.id, [...(result.entity.tags ?? [])].sort());
+  }
+  return tagsById;
+}
+
+function tagsForTargets(
+  targetIds: readonly string[],
+  tagsByRequirementId: ReadonlyMap<string, readonly string[]>,
+): readonly string[] {
+  return [
+    ...new Set(
+      targetIds.flatMap((targetId) => tagsByRequirementId.get(targetId) ?? []),
+    ),
+  ].sort();
+}
+
+function hasSharedRequirementTag(
+  targetIds: readonly string[],
+  tagsByRequirementId: ReadonlyMap<string, readonly string[]>,
+): boolean {
+  const tagSets = targetIds
+    .map((targetId) => new Set(tagsByRequirementId.get(targetId) ?? []))
+    .filter((tagSet) => tagSet.size > 0);
+  const first = tagSets[0];
+  if (first === undefined || tagSets.length !== targetIds.length) return false;
+  return [...first].some((tag) => tagSets.every((tagSet) => tagSet.has(tag)));
+}
+
+function isMixedPurposeCandidate(symbol: SymbolMetadata): boolean {
+  return AGGREGATE_KINDS.has(symbol.kind) || isModuleOrConfig(symbol);
+}
+
+function createMixedPurposeDiagnostics(
+  symbols: readonly SymbolMetadata[],
+  options: SymbolQualityDiagnosticsOptions,
+): readonly KibiImpactDiagnostic[] {
+  const tagsByRequirementId = requirementTagsById(options.manifestResults);
+  return symbols.flatMap((symbol) => {
+    if (!isMixedPurposeCandidate(symbol)) return [];
+    const manifestChildren = narrowerManifestSymbols(symbol, symbols);
+    const extractedChildren = narrowerExtractedSymbols(
+      symbol,
+      options.symbolsByFile,
+    );
+    if (manifestChildren.length === 0 && extractedChildren.length === 0)
+      return [];
+    const requirementTags = tagsForTargets(
+      symbol.requirementTargetIds,
+      tagsByRequirementId,
+    );
+    if (requirementTags.length < 3) return [];
+    if (
+      hasSharedRequirementTag(symbol.requirementTargetIds, tagsByRequirementId)
+    ) {
+      return [];
+    }
+    const narrowerSymbolIds = [
+      ...new Set([
+        ...manifestChildren.map((child) => child.id),
+        ...extractedChildren.map((child) => child.id),
+      ]),
+    ].sort();
+
+    return [
+      {
+        id: "component_mixed_purpose_review",
+        severity: "review",
+        blocking: false,
+        category: "mixed-purpose",
+        entityId: symbol.id,
+        source: symbol.source,
+        files: [symbol.source, symbol.sourceFile],
+        docs: ["docs/symbol-traceability-taxonomy.md"],
+        message: `Symbol ${symbol.id} spans unrelated requirement tag clusters while narrower same-file symbols exist.`,
+        suggestion:
+          "Move unrelated requirement ownership to narrower class members/components/services or split the coarse symbol into cohesive behavioral anchors.",
+        evidence: {
+          targetIds: symbol.requirementTargetIds,
+          requirementTags,
+          narrowerSymbolIds,
+          sourceFile: symbol.sourceFile,
+          symbolKind: symbol.kind,
+          symbolRole: symbol.role,
+        },
+      },
+    ];
+  });
+}
+
+export function createSymbolQualityDiagnostics(
+  options: SymbolQualityDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  const symbols = collectSymbols(options);
+  return [
+    ...createMultiRequirementDiagnostics(symbols),
+    ...createDuplicateCoordinateDiagnostics(symbols),
+    ...createMixedPurposeDiagnostics(symbols, options),
+  ];
+}