kibi-cli 0.14.0 → 0.17.0

package/src/public/operations/check-executor.ts

@@ -0,0 +1,185 @@
+import { runAggregatedChecks } from "../../commands/aggregated-checks.js";
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import type { Violation } from "../check-types.js";
+import { collectFullKbQualityDiagnostics } from "../impact-diagnostics.js";
+import {
+  type CheckDiagnostic,
+  type CheckStructuredContent,
+  buildStructuredContent,
+  buildSummary,
+} from "./check-format-shared.js";
+import {
+  analyzeKbCheckImpact,
+  collectQueryPlanSafetyViolations,
+  getEffectiveRules,
+  loadChecksConfig,
+  qualityDiagnosticsFromImpact,
+} from "./check-helpers.js";
+import type { OperationContext, PrologPort } from "./runtime-types.js";
+import type { OperationResult } from "./types.js";
+
+// implements REQ-kibi-operation-interface-parity, REQ-002
+export type CheckInput = {
+  readonly rules?: readonly string[];
+  readonly workspaceRoot?: string;
+  readonly sourceFiles?: readonly string[];
+  readonly staged?: boolean;
+  readonly includeWorkingTreeDiff?: boolean;
+  readonly includeImpactDiagnostics?: boolean;
+  readonly maxDiagnostics?: number;
+};
+
+export type CheckPayload = CheckStructuredContent;
+export type { CheckDiagnostic, CheckStructuredContent };
+export {
+  buildStructuredContent,
+  buildSummary,
+  getEffectiveRules,
+  loadChecksConfig,
+};
+
+export type CheckExecutionOptions = {
+  readonly collectFullQualityDiagnosticsForExplicitRules?: boolean;
+};
+
+function requireProlog(context: OperationContext): PrologPort {
+  if (context.prolog === undefined) {
+    throw new Error("Check operation requires a Prolog runtime");
+  }
+  return context.prolog;
+}
+
+function invalidatePrologCache(prolog: PrologPort): void {
+  prolog.invalidateCache?.();
+}
+
+// implements REQ-kibi-operation-interface-parity, REQ-002
+export async function executeCheck(
+  args: CheckInput,
+  context: OperationContext,
+  options: CheckExecutionOptions = {},
+): Promise<OperationResult<CheckPayload>> {
+  try {
+    const workspaceRoot = args.workspaceRoot ?? context.workspaceRoot;
+    const prolog = requireProlog(context);
+    const checksConfig = await loadChecksConfig(workspaceRoot);
+    const rulesAllowlist =
+      args.rules === undefined
+        ? getEffectiveRules(checksConfig.rules)
+        : args.rules.length === 0
+          ? new Set<string>()
+          : getEffectiveRules(undefined, args.rules.join(","));
+    const hasExplicitRules = args.rules !== undefined;
+    const impactResult = analyzeKbCheckImpact(workspaceRoot, args);
+    const impactQualityDiagnostics = qualityDiagnosticsFromImpact(impactResult);
+    const maxDiagnosticsOption =
+      args.maxDiagnostics !== undefined
+        ? { maxDiagnostics: args.maxDiagnostics }
+        : {};
+
+    if (rulesAllowlist.size === 0) {
+      const qualityDiagnostics =
+        hasExplicitRules &&
+        options.collectFullQualityDiagnosticsForExplicitRules !== true
+          ? []
+          : impactResult
+            ? impactQualityDiagnostics
+            : await collectFullKbQualityDiagnostics({
+                prolog,
+                ...maxDiagnosticsOption,
+              });
+      return {
+        content: [
+          {
+            type: "text",
+            text: buildSummary({
+              violations: [],
+              impactResult,
+              qualityDiagnostics,
+            }),
+          },
+        ],
+        structuredContent: buildStructuredContent({
+          violations: [],
+          diagnostics: [],
+          qualityDiagnostics,
+          impactResult,
+        }),
+      };
+    }
+
+    invalidatePrologCache(prolog);
+
+    const aggregatedViolations = await runAggregatedChecks(
+      prolog,
+      rulesAllowlist,
+      checksConfig.symbolTraceability.requireAdr,
+    );
+    const queryPlanViolations = rulesAllowlist.has("query-plan-safety")
+      ? collectQueryPlanSafetyViolations()
+      : [];
+    const violations: Violation[] = [
+      ...aggregatedViolations,
+      ...queryPlanViolations,
+    ];
+
+    const diagnostics: CheckDiagnostic[] = violations.map((v) => ({
+      category: "SYNC_ERROR",
+      severity: "error",
+      message: v.description,
+      ...(v.source !== undefined ? { file: v.source } : {}),
+      ...(v.suggestion !== undefined ? { suggestion: v.suggestion } : {}),
+    }));
+
+    const collectFullQualityDiagnostics =
+      !hasExplicitRules ||
+      options.collectFullQualityDiagnosticsForExplicitRules === true;
+    const qualityDiagnostics = !collectFullQualityDiagnostics
+      ? impactQualityDiagnostics
+      : impactResult
+        ? impactQualityDiagnostics
+        : await collectFullKbQualityDiagnostics({
+            prolog,
+            hardViolationEntityIds: new Set(violations.map((v) => v.entityId)),
+            ...maxDiagnosticsOption,
+          });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: buildSummary({
+            violations,
+            impactResult,
+            qualityDiagnostics,
+          }),
+        },
+      ],
+      structuredContent: buildStructuredContent({
+        violations,
+        diagnostics,
+        qualityDiagnostics,
+        impactResult,
+      }),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Check execution failed: ${message}`);
+  }
+}

package/src/public/operations/check-format-shared.ts

@@ -0,0 +1,178 @@
+import type { Violation } from "../check-types.js";
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import type { ChangedFileImpactResult } from "../impact-diagnostics.js";
+import type { QualityDiagnostic } from "../impact-diagnostics.js";
+
+// implements REQ-mcp-tool-check
+export interface CheckDiagnostic {
+  readonly category: string;
+  readonly severity: "error" | "warning";
+  readonly message: string;
+  readonly file?: string;
+  readonly suggestion?: string;
+}
+
+// implements REQ-mcp-tool-check
+export interface CheckStructuredContent {
+  readonly violations: readonly Violation[];
+  readonly count: number;
+  readonly diagnostics: readonly CheckDiagnostic[];
+  readonly qualityDiagnostics?: readonly QualityDiagnostic[];
+  readonly impactDiagnostics?: ChangedFileImpactResult["impactDiagnostics"];
+  readonly sourceFiles?: ChangedFileImpactResult["sourceFiles"];
+  readonly extractedSymbols?: ChangedFileImpactResult["extractedSymbols"];
+  readonly linkedEntities?: ChangedFileImpactResult["linkedEntities"];
+  readonly nextActions?: ChangedFileImpactResult["nextActions"];
+}
+
+function formatDiagnostics(diagnostics: readonly CheckDiagnostic[]) {
+  return diagnostics.map((d) => ({
+    category: d.category,
+    severity: d.severity,
+    message: d.message,
+    ...(d.file !== undefined ? { file: d.file } : {}),
+    ...(d.suggestion !== undefined ? { suggestion: d.suggestion } : {}),
+  }));
+}
+
+// implements REQ-mcp-tool-check
+export function formatImpactText(
+  impactResult: ChangedFileImpactResult,
+): string {
+  if (impactResult.impactDiagnostics.length === 0) {
+    return "No impact diagnostics found";
+  }
+
+  const details = impactResult.impactDiagnostics.map((diagnostic) => {
+    const files =
+      diagnostic.files.length > 0
+        ? diagnostic.files.join(", ")
+        : "unknown-source";
+    return `- ${diagnostic.id} | ${diagnostic.severity} | ${files} | ${diagnostic.message} Suggestion: ${diagnostic.suggestion}`;
+  });
+  return `${impactResult.impactDiagnostics.length} impact diagnostics found\n${details.join("\n")}`;
+}
+
+function formatOptionalList(
+  label: string,
+  values: readonly string[] | undefined,
+) {
+  if (values === undefined || values.length === 0) {
+    return [];
+  }
+  return [`${label}: ${values.join(", ")}`];
+}
+
+// implements REQ-mcp-tool-check
+export function formatQualityDiagnosticsText(
+  diagnostics: readonly QualityDiagnostic[],
+): string {
+  if (diagnostics.length === 0) {
+    return "No quality diagnostics found";
+  }
+
+  const details = diagnostics.map((diagnostic) => {
+    const parts = [
+      diagnostic.id,
+      diagnostic.severity,
+      diagnostic.category,
+      diagnostic.message,
+    ];
+    const metadata = [
+      `Blocking: ${diagnostic.blocking ? "yes" : "no"}`,
+      ...formatOptionalList("Files", diagnostic.files),
+      ...formatOptionalList("Docs", diagnostic.docs),
+      ...(diagnostic.entityId !== undefined
+        ? [`Entity: ${diagnostic.entityId}`]
+        : []),
+      ...(diagnostic.source !== undefined
+        ? [`Source: ${diagnostic.source}`]
+        : []),
+      `Suggestion: ${diagnostic.suggestion}`,
+    ];
+    return `- ${parts.join(" | ")}\n  ${metadata.join("\n  ")}`;
+  });
+
+  return `${diagnostics.length} quality diagnostic${diagnostics.length === 1 ? "" : "s"} found\n${details.join("\n")}`;
+}
+
+// implements REQ-mcp-tool-check
+export function formatViolationText(violations: readonly Violation[]): string {
+  if (violations.length === 0) {
+    return "No violations found";
+  }
+
+  const details = violations.map((violation) => {
+    const parts = [
+      violation.rule,
+      violation.entityId,
+      violation.source ?? "unknown-source",
+      violation.description,
+    ];
+    if (violation.suggestion) {
+      parts.push(`Suggestion: ${violation.suggestion}`);
+    }
+    return `- ${parts.join(" | ")}`;
+  });
+
+  return `${violations.length} violations found\n${details.join("\n")}`;
+}
+
+// implements REQ-mcp-tool-check
+export function buildStructuredContent(input: {
+  violations: readonly Violation[];
+  diagnostics: readonly CheckDiagnostic[];
+  qualityDiagnostics?: readonly QualityDiagnostic[];
+  impactResult: ChangedFileImpactResult | undefined;
+}): CheckStructuredContent {
+  const qualityDiagnostics = input.qualityDiagnostics ?? [];
+  return {
+    violations: [...input.violations],
+    count: input.violations.length,
+    diagnostics: formatDiagnostics(input.diagnostics),
+    ...(qualityDiagnostics.length > 0
+      ? { qualityDiagnostics: [...qualityDiagnostics] }
+      : {}),
+    ...(input.impactResult
+      ? {
+          impactDiagnostics: input.impactResult.impactDiagnostics,
+          sourceFiles: input.impactResult.sourceFiles,
+          extractedSymbols: input.impactResult.extractedSymbols,
+          linkedEntities: input.impactResult.linkedEntities,
+          nextActions: input.impactResult.nextActions,
+        }
+      : {}),
+  };
+}
+
+// implements REQ-mcp-tool-check
+export function buildSummary(input: {
+  readonly violations: readonly Violation[];
+  readonly impactResult: ChangedFileImpactResult | undefined;
+  readonly qualityDiagnostics: readonly QualityDiagnostic[];
+}): string {
+  const sections = [formatViolationText(input.violations)];
+  if (input.impactResult !== undefined) {
+    sections.push(formatImpactText(input.impactResult));
+  }
+  if (input.qualityDiagnostics.length > 0) {
+    sections.push(formatQualityDiagnosticsText(input.qualityDiagnostics));
+  }
+  return sections.join("\n");
+}

package/src/public/operations/check-helpers.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { getKbPlPathOverride } from "../../env.js";
+import { resolveKbPlPath } from "../../prolog.js";
+import { analyzePrologQueryPlanSafety } from "../../utils/prolog-query-plan-safety.js";
+import {
+  type ChecksConfig,
+  DEFAULT_CHECKS_CONFIG,
+  RULE_NAMES,
+  type Violation,
+  getEffectiveRules,
+} from "../../utils/rule-registry.js";
+import {
+  type ChangedFileImpactResult,
+  type QualityDiagnostic,
+  analyzeChangedFileImpact,
+} from "../impact-diagnostics.js";
+import type { CheckInput } from "./check-executor.js";
+
+export { RULE_NAMES, getEffectiveRules };
+
+function resolveChecksPlPath(): string {
+  const override = getKbPlPathOverride();
+  return path.join(path.dirname(override ?? resolveKbPlPath()), "checks.pl");
+}
+
+// implements REQ-mcp-tool-check
+export function collectQueryPlanSafetyViolations(): Violation[] {
+  const checksPlPath = resolveChecksPlPath();
+  const source = readFileSync(checksPlPath, "utf8");
+  return analyzePrologQueryPlanSafety(source).map((v) => ({
+    rule: "query-plan-safety",
+    entityId: v.predicate,
+    description: v.description,
+    suggestion: v.suggestion,
+    source: `${checksPlPath}:${v.line}`,
+  }));
+}
+
+// implements REQ-mcp-tool-check
+export async function loadChecksConfig(
+  workspaceRoot: string,
+): Promise<ChecksConfig> {
+  const configPath = path.join(workspaceRoot, ".kb", "config.json");
+  try {
+    const content = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(content) as {
+      checks?: Partial<ChecksConfig>;
+    };
+
+    const parsedRules = parsed.checks?.rules;
+    const normalizedRules: Record<string, boolean> = {
+      ...DEFAULT_CHECKS_CONFIG.rules,
+    };
+    if (parsedRules && typeof parsedRules === "object") {
+      for (const [key, value] of Object.entries(parsedRules)) {
+        if (typeof value === "boolean") {
+          normalizedRules[key] = value;
+        }
+      }
+    }
+
+    const parsedSt = parsed.checks?.symbolTraceability;
+    const normalizedSt = { ...DEFAULT_CHECKS_CONFIG.symbolTraceability };
+    if (
+      parsedSt &&
+      typeof parsedSt === "object" &&
+      typeof parsedSt.requireAdr === "boolean"
+    ) {
+      normalizedSt.requireAdr = parsedSt.requireAdr;
+    }
+
+    return { rules: normalizedRules, symbolTraceability: normalizedSt };
+  } catch {
+    return DEFAULT_CHECKS_CONFIG;
+  }
+}
+
+// implements REQ-mcp-tool-check
+export function hasImpactOptions(args: CheckInput): boolean {
+  return Boolean(
+    args.includeImpactDiagnostics ||
+      args.staged ||
+      args.includeWorkingTreeDiff ||
+      (args.sourceFiles !== undefined && args.sourceFiles.length > 0),
+  );
+}
+
+// implements REQ-mcp-tool-check
+export function analyzeKbCheckImpact(
+  workspaceRoot: string,
+  args: CheckInput,
+): ChangedFileImpactResult | undefined {
+  if (!hasImpactOptions(args)) {
+    return undefined;
+  }
+  return analyzeChangedFileImpact({
+    workspaceRoot,
+    ...(args.sourceFiles !== undefined
+      ? { sourceFiles: args.sourceFiles }
+      : {}),
+    ...(args.staged !== undefined ? { staged: args.staged } : {}),
+    ...(args.includeWorkingTreeDiff !== undefined
+      ? { includeWorkingTreeDiff: args.includeWorkingTreeDiff }
+      : {}),
+    ...(args.includeImpactDiagnostics !== undefined
+      ? { includeImpactDiagnostics: args.includeImpactDiagnostics }
+      : {}),
+    ...(args.maxDiagnostics !== undefined
+      ? { maxDiagnostics: args.maxDiagnostics }
+      : {}),
+  });
+}
+
+// implements REQ-mcp-tool-check
+export function qualityDiagnosticsFromImpact(
+  impactResult: ChangedFileImpactResult | undefined,
+): readonly QualityDiagnostic[] {
+  if (impactResult === undefined) return [];
+  return impactResult.impactDiagnostics.filter(
+    (d) => !d.blocking && d.severity !== "error",
+  );
+}

package/src/public/operations/discovery-entities.ts

@@ -0,0 +1,122 @@
+import {
+  escapeAtomContent,
+  parseEntityFromBinding,
+  parseEntityFromList,
+  parseListOfLists,
+} from "../../prolog/codec.js";
+import type { PrologPort } from "./runtime-types.js";
+
+export type EntityQueryInput = {
+  readonly type?: string;
+  readonly id?: string;
+  readonly tags?: readonly string[];
+  readonly sourceFile?: string;
+};
+
+export const VALID_ENTITY_TYPES = [
+  "req",
+  "scenario",
+  "test",
+  "adr",
+  "flag",
+  "event",
+  "symbol",
+  "fact",
+] as const;
+
+// implements REQ-002, REQ-013
+export function validateEntityType(type?: string): void {
+  if (type && !VALID_ENTITY_TYPES.some((candidate) => candidate === type)) {
+    throw new Error(
+      `Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`,
+    );
+  }
+}
+
+// implements REQ-002, REQ-013
+export function buildEntityGoal(input: EntityQueryInput): string {
+  const { type, id, tags, sourceFile } = input;
+  if (sourceFile) {
+    const safeSource = escapeAtomContent(sourceFile);
+    if (type) {
+      const safeType = escapeAtomContent(type);
+      return `findall([Id,'${safeType}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${safeType}', Props)), Results)`;
+    }
+    return `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
+  }
+  if (id && type) {
+    const safeId = escapeAtomContent(id);
+    const safeType = escapeAtomContent(type);
+    return `findall(['${safeId}','${safeType}',Props], kb_entity('${safeId}', '${safeType}', Props), Results)`;
+  }
+  if (id) {
+    const safeId = escapeAtomContent(id);
+    return `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
+  }
+  if (tags && tags.length > 0) {
+    if (type) {
+      const safeType = escapeAtomContent(type);
+      return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+    }
+    return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+  }
+  if (type) {
+    const safeType = escapeAtomContent(type);
+    return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+  }
+  return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+}
+
+// implements REQ-002, REQ-013
+export async function loadEntities(
+  prolog: Pick<PrologPort, "query">,
+  input: EntityQueryInput,
+): Promise<Record<string, unknown>[]> {
+  validateEntityType(input.type);
+  const queryResult = await prolog.query(buildEntityGoal(input));
+  if (!queryResult.success) {
+    throw new Error(queryResult.error || "Query failed with unknown error");
+  }
+
+  let entities: Record<string, unknown>[] = [];
+  const resultsBinding = queryResult.bindings.Results;
+  const resultBinding = queryResult.bindings.Result;
+  if (resultsBinding) {
+    entities = parseListOfLists(resultsBinding).map(parseEntityFromList);
+  } else if (resultBinding) {
+    entities = [parseEntityFromBinding(resultBinding)];
+  }
+  if (input.tags && input.tags.length > 0) {
+    const requested = new Set(input.tags.map((tag) => tag.trim()));
+    entities = entities.filter((entity) => {
+      const tags = entity.tags;
+      return (
+        Array.isArray(tags) &&
+        tags.some((tag) => requested.has(String(tag).trim()))
+      );
+    });
+  }
+  return dedupeEntities(entities);
+}
+
+// implements REQ-002
+export function paginateResults<T>(
+  results: readonly T[],
+  limit = 100,
+  offset = 0,
+): T[] {
+  return results.slice(offset, offset + limit);
+}
+
+// implements REQ-002
+export function dedupeEntities(
+  entities: readonly Record<string, unknown>[],
+): Record<string, unknown>[] {
+  const seen = new Set<string>();
+  return entities.filter((entity) => {
+    const key = `${String(entity.type ?? "")}::${String(entity.id ?? "")}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}