kibi-cli 2.21.2 → 2.22.0

package/src/public/operations/symbol-granularity-check.ts

@@ -0,0 +1,233 @@
+/*
+ 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 { readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import type { ExtractionResult } from "../../extractors/markdown.js";
+import { createMaintenanceSourceAnalysisService } from "../../plugins/maintenance-source-analysis.js";
+import {
+  normalizeEntityId,
+  parseEntityFromList,
+  parseListOfLists,
+  parseTriples,
+} from "../../prolog/codec.js";
+import {
+  type ExtractedSymbol,
+  extractSymbolsFromStagedFileAsync,
+} from "../../traceability/symbol-extract.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import { createSymbolGranularityDiagnostics } from "../impact/diagnostics.js";
+import { createImpactManifestLookup } from "../impact/manifest.js";
+import { normalizeSourceFile } from "../impact/source-changes.js";
+import {
+  isAllowedGranularityReason,
+  isTraceabilityRelationshipType,
+} from "../symbol-granularity.js";
+import type { PrologPort } from "./runtime-types.js";
+
+/**
+ * Full-check form of the staged gate's `symbol_granularity_violation`: a
+ * symbol with traceability relationships must not link its source file
+ * coarsely while narrower behavioral symbols are available, unless it carries
+ * an allowed granularity_reason.
+ */
+// implements REQ-cli-check, REQ-cli-staged-impact-enforcement
+export const SYMBOL_GRANULARITY_RULE = "symbol-granularity";
+
+const SYMBOL_ROWS_QUERY =
+  "findall([Id,symbol,Fields], (kb_entity(Id, symbol, Props), include([Key=_]>>memberchk(Key, [title,status,source,sourceFile,granularity_reason]), Props, Fields)), Rows)";
+const SYMBOL_RELATIONSHIPS_QUERY =
+  "findall([From,To,Type], (member(Type, [implements,covered_by,executable_for]), kb_relationship(Type, From, To), kb_entity(From, symbol, _)), Rels)";
+
+function stringField(
+  entity: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = entity[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+// implements REQ-cli-check
+async function loadSymbolResults(
+  prolog: Pick<PrologPort, "query">,
+  workspaceRoot: string,
+): Promise<ExtractionResult[]> {
+  const rows = await prolog.query(SYMBOL_ROWS_QUERY);
+  if (!rows.success) {
+    throw new Error(
+      `symbol-granularity symbol projection failed: ${rows.error ?? "unknown error"}`,
+    );
+  }
+  const rels = await prolog.query(SYMBOL_RELATIONSHIPS_QUERY);
+  if (!rels.success) {
+    throw new Error(
+      `symbol-granularity relationship projection failed: ${rels.error ?? "unknown error"}`,
+    );
+  }
+
+  const relationships = new Map<string, ExtractionResult["relationships"]>();
+  for (const [rawFrom, rawTo, type] of parseTriples(
+    rels.bindings.Rels ?? "[]",
+  )) {
+    const from = normalizeEntityId(rawFrom);
+    const current = relationships.get(from) ?? [];
+    current.push({ from, to: normalizeEntityId(rawTo), type });
+    relationships.set(from, current);
+  }
+
+  const results: ExtractionResult[] = [];
+  for (const row of parseListOfLists(rows.bindings.Rows ?? "[]")) {
+    const entity = parseEntityFromList(row);
+    const id = stringField(entity, "id");
+    const sourceFile = stringField(entity, "sourceFile");
+    if (id === undefined || sourceFile === undefined) continue;
+    const granularityReason = stringField(entity, "granularity_reason");
+    results.push({
+      entity: {
+        id,
+        type: "symbol",
+        title: stringField(entity, "title") ?? "",
+        status: stringField(entity, "status") ?? "",
+        created_at: "",
+        updated_at: "",
+        source: stringField(entity, "source") ?? "",
+        ...(granularityReason !== undefined
+          ? { granularity_reason: granularityReason }
+          : {}),
+      },
+      relationships: relationships.get(id) ?? [],
+      sourceFile: normalizeSourceFile(workspaceRoot, sourceFile),
+    });
+  }
+  return results;
+}
+
+/**
+ * The symbols the staged gate would judge: they carry a traceability
+ * relationship and no allowed granularity_reason. Other symbols are exempt,
+ * so their source files need no analysis.
+ */
+// implements REQ-cli-check
+function granularityCandidates(
+  results: readonly ExtractionResult[],
+): ExtractionResult[] {
+  return results.filter(
+    (result) =>
+      result.relationships.some((relationship) =>
+        isTraceabilityRelationshipType(relationship.type),
+      ) && !isAllowedGranularityReason(result.entity.granularity_reason),
+  );
+}
+
+function readRegularFile(absolutePath: string): string | null {
+  try {
+    if (!statSync(absolutePath).isFile()) return null;
+    return readFileSync(absolutePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// implements REQ-cli-check
+async function analyzeFiles(
+  files: readonly string[],
+  results: readonly ExtractionResult[],
+  workspaceRoot: string,
+): Promise<Map<string, readonly ExtractedSymbol[]>> {
+  const manifestLookup = createImpactManifestLookup(results);
+  const service = createMaintenanceSourceAnalysisService(workspaceRoot);
+  const analyses = new Map<string, readonly ExtractedSymbol[]>();
+  for (const file of files) {
+    const content = readRegularFile(path.resolve(workspaceRoot, file));
+    if (content === null) continue;
+    try {
+      const analysis = await service.analyzeTextV2(file, content);
+      // Only a complete parser-backed analysis decides; the staged gate
+      // reports an incomplete one itself when the file is touched.
+      if (analysis.status !== "ok") continue;
+      const symbols = await extractSymbolsFromStagedFileAsync(
+        {
+          path: file,
+          status: "M",
+          content,
+          hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+        },
+        manifestLookup,
+        { analyzeText: async () => analysis },
+      );
+      analyses.set(file, symbols);
+    } catch {
+      // An analysis failure cannot decide anything for this file.
+    }
+  }
+  return analyses;
+}
+
+// implements REQ-cli-check
+function granularityViolations(
+  candidates: readonly ExtractionResult[],
+  sourceSymbolsByFile: ReadonlyMap<string, readonly ExtractedSymbol[]>,
+  workspaceRoot: string,
+): Violation[] {
+  return createSymbolGranularityDiagnostics({
+    manifestResults: candidates.filter(
+      (result) =>
+        result.sourceFile !== undefined &&
+        sourceSymbolsByFile.has(result.sourceFile),
+    ),
+    symbolsByFile: new Map(),
+    sourceSymbolsByFile,
+    workspaceRoot,
+  }).map((diagnostic) => ({
+    rule: SYMBOL_GRANULARITY_RULE,
+    entityId: diagnostic.entityId ?? "",
+    description: diagnostic.message,
+    suggestion: diagnostic.suggestion,
+    ...(diagnostic.source !== undefined ? { source: diagnostic.source } : {}),
+    evidence: {
+      diagnosticId: diagnostic.id,
+      ...(diagnostic.evidence ?? {}),
+    },
+  }));
+}
+
+/**
+ * `symbol-granularity`: the staged gate's granularity predicate, evaluated
+ * for every symbol against its whole working-tree file, every declaration a
+ * candidate as if the file were fully staged. Only files of symbols the gate
+ * would judge are analyzed; a file the source analyzers cannot fully analyze
+ * is skipped.
+ */
+// implements REQ-cli-check, REQ-cli-staged-impact-enforcement
+export async function collectSymbolGranularityViolations(
+  prolog: Pick<PrologPort, "query">,
+  workspaceRoot: string,
+  rules: ReadonlySet<string>,
+): Promise<Violation[]> {
+  if (!rules.has(SYMBOL_GRANULARITY_RULE)) return [];
+  const results = await loadSymbolResults(prolog, workspaceRoot);
+  const candidates = granularityCandidates(results);
+  const files = [
+    ...new Set(candidates.map((result) => result.sourceFile ?? "")),
+  ]
+    .filter((file) => file.length > 0)
+    .sort();
+  if (files.length === 0) return [];
+  const analyses = await analyzeFiles(files, results, workspaceRoot);
+  return granularityViolations(candidates, analyses, workspaceRoot);
+}

package/src/public/symbol-granularity.ts

@@ -117,6 +117,43 @@ export function getBehavioralSymbolNames(
   ].sort();
 }
 
+/**
+ * The candidates that are narrower than a manifest symbol: members of it
+ * (`Title.member`), or, when the source declares no symbol named like it,
+ * every other declaration in the file.
+ */
+// implements REQ-symbol-behavioral-anchors, REQ-cli-schema-migration
+export function narrowerSymbols<T extends { name: string }>(
+  manifestSymbolName: string,
+  candidates: readonly T[],
+  sourceSymbols: readonly { name: string }[],
+): T[] {
+  const declared = sourceSymbols.some(
+    (symbol) => symbol.name === manifestSymbolName,
+  );
+  return candidates.filter(
+    (candidate) =>
+      candidate.name !== manifestSymbolName &&
+      (candidate.name.startsWith(`${manifestSymbolName}.`) || !declared),
+  );
+}
+
+/**
+ * The behavioral symbols that make a traceability link on
+ * `manifestSymbolName` coarse: the staged granularity gate blocks such a
+ * link unless it carries a granularity_reason, and `kibi migrate` marks
+ * exactly these links legacy-link. Empty when the link is narrow enough.
+ */
+// implements REQ-symbol-behavioral-anchors, REQ-cli-schema-migration
+export function coarseLinkBehavioralNames(
+  manifestSymbolName: string,
+  sourceSymbols: readonly GranularSymbolCandidate[],
+): string[] {
+  return getBehavioralSymbolNames(
+    narrowerSymbols(manifestSymbolName, sourceSymbols, sourceSymbols),
+  );
+}
+
 export function getNonBehavioralSymbolNames(
   candidates: GranularSymbolCandidate[],
 ): string[] {