kibi-cli 0.8.0 → 0.10.1

package/dist/utils/strict-modeling.js

@@ -0,0 +1,371 @@
+/*
+ * 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 { createHash } from "node:crypto";
+import * as path from "node:path";
+import { DEFAULT_CONFIG } from "./config.js";
+const STRICT_CONFIDENCE_THRESHOLD = 0.7;
+export function normalizeSubjectKey(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[\\/]+/g, ".")
+        .replace(/[^a-z0-9.]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/\.+/g, ".")
+        .replace(/(^[._]+|[._]+$)/g, "");
+    if (!normalized) {
+        throw new Error("Semantic claim subjectKey must normalize to a non-empty value");
+    }
+    return normalized;
+}
+export function normalizePropertyKey(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!normalized) {
+        throw new Error("Semantic claim propertyKey must normalize to a non-empty value");
+    }
+    return normalized;
+}
+export function buildStableRequirementIds(claim) {
+    const normalizedSource = normalizeSourceKey(claim.source);
+    const normalizedSubjectKey = normalizeSubjectKey(claim.subjectKey);
+    const normalizedPropertyKey = normalizePropertyKey(claim.propertyKey);
+    const normalizedValue = normalizeStableValue(claim.value);
+    const stableKey = [
+        normalizedSource,
+        normalizedSubjectKey,
+        normalizedPropertyKey,
+        claim.operator,
+        normalizedValue,
+    ].join(":");
+    return {
+        stableKey,
+        reqId: buildEntityId("REQ-AUTO", `req:${stableKey}`),
+        subjectFactId: buildEntityId("FACT-SUBJECT", `subject:${stableKey}`),
+        propertyFactId: buildEntityId("FACT-PROP", `property:${stableKey}`),
+        observationFactId: buildEntityId("FACT-OBS", `observation:${stableKey}`),
+        normalizedSource,
+        normalizedSubjectKey,
+        normalizedPropertyKey,
+        normalizedValue,
+    };
+}
+export function buildStrictWriteSet(input) {
+    const statement = normalizeStatement(input.statement);
+    const confidence = normalizeConfidence(input.claim.confidence);
+    const ids = buildStableRequirementIds(input.claim);
+    const textRef = normalizeTextRef(input.claim.provenance, input.claim.source);
+    const metadataTags = buildMetadataTags({
+        confidence,
+        provenance: textRef,
+    });
+    const sourcePaths = resolveEntitySourcePaths(input.config?.paths);
+    if (confidence < STRICT_CONFIDENCE_THRESHOLD) {
+        return {
+            observationFact: {
+                type: "fact",
+                id: ids.observationFactId,
+                properties: {
+                    id: ids.observationFactId,
+                    title: statement,
+                    status: "active",
+                    source: buildEntitySourcePath(sourcePaths.facts, ids.observationFactId),
+                    text_ref: textRef,
+                    tags: buildUniqueTags([...metadataTags, "lane:observation", "review:required"]),
+                    fact_kind: "observation",
+                    subject_key: ids.normalizedSubjectKey,
+                    property_key: ids.normalizedPropertyKey,
+                    canonical_key: ids.stableKey,
+                },
+            },
+            relationships: [],
+            isStrict: false,
+            confidence,
+        };
+    }
+    const req = {
+        type: "req",
+        id: ids.reqId,
+        properties: {
+            id: ids.reqId,
+            title: statement,
+            status: "open",
+            source: buildEntitySourcePath(sourcePaths.requirements, ids.reqId),
+            text_ref: textRef,
+            tags: buildUniqueTags([...metadataTags, "lane:strict"]),
+        },
+    };
+    const subjectFact = {
+        type: "fact",
+        id: ids.subjectFactId,
+        properties: {
+            id: ids.subjectFactId,
+            title: humanizeKey(ids.normalizedSubjectKey),
+            status: "active",
+            source: buildEntitySourcePath(sourcePaths.facts, ids.subjectFactId),
+            text_ref: textRef,
+            tags: buildUniqueTags([...metadataTags, "lane:strict", "fact:subject"]),
+            fact_kind: "subject",
+            subject_key: ids.normalizedSubjectKey,
+            canonical_key: ids.normalizedSubjectKey,
+        },
+    };
+    const propertyFact = {
+        type: "fact",
+        id: ids.propertyFactId,
+        properties: {
+            id: ids.propertyFactId,
+            title: buildPropertyFactTitle(ids.normalizedPropertyKey, input.claim),
+            status: "active",
+            source: buildEntitySourcePath(sourcePaths.facts, ids.propertyFactId),
+            text_ref: textRef,
+            tags: buildUniqueTags([...metadataTags, "lane:strict", "fact:property_value"]),
+            fact_kind: "property_value",
+            subject_key: ids.normalizedSubjectKey,
+            property_key: ids.normalizedPropertyKey,
+            canonical_key: ids.stableKey,
+            ...buildPropertyFactFields(input.claim),
+        },
+    };
+    const relationships = dedupeRelationships([
+        {
+            type: "constrains",
+            from: req.id,
+            to: subjectFact.id,
+            source: input.claim.source,
+            confidence,
+        },
+        {
+            type: "requires_property",
+            from: req.id,
+            to: propertyFact.id,
+            source: input.claim.source,
+            confidence,
+        },
+    ]);
+    return {
+        req,
+        subjectFact,
+        propertyFact,
+        relationships,
+        isStrict: true,
+        confidence,
+    };
+}
+export function modelRequirementClaims(inputs) {
+    const seen = new Set();
+    const modeled = [];
+    for (const input of inputs) {
+        const writeSet = buildStrictWriteSet(input);
+        const stableId = writeSet.isStrict ? writeSet.req.id : writeSet.observationFact.id;
+        if (seen.has(stableId)) {
+            continue;
+        }
+        seen.add(stableId);
+        modeled.push(writeSet);
+    }
+    return modeled;
+}
+function buildEntityId(prefix, value) {
+    const hash = createHash("sha256");
+    hash.update(value);
+    return `${prefix}-${hash.digest("hex").substring(0, 16).toUpperCase()}`;
+}
+function normalizeSourceKey(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/(^-|-$)/g, "");
+    if (!normalized) {
+        throw new Error("Semantic claim source must normalize to a non-empty value");
+    }
+    return normalized;
+}
+function normalizeStableValue(value) {
+    if (typeof value === "string") {
+        const normalized = value
+            .trim()
+            .toLowerCase()
+            .replace(/\s+/g, "_")
+            .replace(/[^a-z0-9._-]+/g, "_")
+            .replace(/_+/g, "_")
+            .replace(/^_+|_+$/g, "");
+        return normalized || "empty";
+    }
+    return String(value);
+}
+function normalizeStatement(statement) {
+    const normalized = statement.trim();
+    if (!normalized) {
+        throw new Error("Strict modeling requires a non-empty prose statement");
+    }
+    return normalized;
+}
+function normalizeTextRef(provenance, source) {
+    const value = provenance?.trim() || source.trim();
+    if (!value) {
+        throw new Error("Strict modeling requires claim provenance or source");
+    }
+    return value;
+}
+function normalizeConfidence(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.round(Math.min(1, Math.max(0, value)) * 100) / 100;
+}
+function toConfidenceBand(confidence) {
+    if (confidence >= 0.9)
+        return "high";
+    if (confidence >= 0.8)
+        return "medium";
+    return "low";
+}
+function buildMetadataTags({ confidence, provenance, }) {
+    return buildUniqueTags([
+        "strict-modeling",
+        `confidence:${confidence.toFixed(2)}`,
+        `confidence-band:${toConfidenceBand(confidence)}`,
+        `provenance:${normalizeSourceKey(provenance)}`,
+    ]);
+}
+function buildUniqueTags(tags) {
+    return Array.from(new Set(tags));
+}
+function buildPropertyFactTitle(normalizedPropertyKey, claim) {
+    const label = humanizeKey(normalizedPropertyKey);
+    if (claim.operator === "polarity") {
+        return `${label} ${normalizePolarityValue(claim.value)}`;
+    }
+    const operatorLabel = claim.operator === "bool"
+        ? "="
+        : claim.operator === "eq"
+            ? "="
+            : claim.operator === "neq"
+                ? "!="
+                : claim.operator === "gte"
+                    ? ">="
+                    : "<=";
+    return `${label} ${operatorLabel} ${String(claim.value)}`;
+}
+function buildPropertyFactFields(claim) {
+    if (claim.operator === "polarity") {
+        return {
+            polarity: normalizePolarityValue(claim.value),
+        };
+    }
+    if (claim.operator === "bool") {
+        return {
+            operator: "eq",
+            value_type: "bool",
+            value_bool: normalizeBooleanValue(claim.value),
+        };
+    }
+    return {
+        operator: claim.operator,
+        ...buildTypedValueFields(claim.value),
+    };
+}
+function buildTypedValueFields(value) {
+    if (typeof value === "boolean") {
+        return {
+            value_type: "bool",
+            value_bool: value,
+        };
+    }
+    if (typeof value === "number") {
+        if (Number.isInteger(value)) {
+            return {
+                value_type: "int",
+                value_int: value,
+            };
+        }
+        return {
+            value_type: "number",
+            value_number: value,
+        };
+    }
+    return {
+        value_type: "string",
+        value_string: value,
+    };
+}
+function normalizePolarityValue(value) {
+    if (typeof value === "boolean") {
+        return value ? "require" : "forbid";
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "require" || normalized === "forbid") {
+            return normalized;
+        }
+    }
+    throw new Error("Polarity claims must use a boolean or the string 'require'/'forbid'");
+}
+function normalizeBooleanValue(value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "true")
+            return true;
+        if (normalized === "false")
+            return false;
+    }
+    throw new Error("Boolean claims must use a boolean or the string 'true'/'false'");
+}
+function humanizeKey(value) {
+    return value
+        .split(/[._-]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function dedupeRelationships(relationships) {
+    const seen = new Set();
+    const deduped = [];
+    for (const relationship of relationships) {
+        const key = `${relationship.type}:${relationship.from}:${relationship.to}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(relationship);
+    }
+    return deduped;
+}
+function resolveEntitySourcePaths(configPaths) {
+    return {
+        requirements: normalizeEntityDirectory(configPaths?.requirements, DEFAULT_CONFIG.paths.requirements),
+        facts: normalizeEntityDirectory(configPaths?.facts, DEFAULT_CONFIG.paths.facts),
+    };
+}
+function normalizeEntityDirectory(directory, fallback) {
+    const selected = directory?.trim() || fallback?.trim() || "documentation";
+    return selected.split(path.sep).join("/").replace(/\/+$/g, "");
+}
+function buildEntitySourcePath(directory, entityId) {
+    return `${directory}/${entityId}.md`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.8.0",
+  "version": "0.10.1",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -79,9 +79,18 @@
       "types": "./dist/public/brief-config.d.ts",
       "default": "./dist/public/brief-config.js"
     },
+    "./schema-version": {
+      "types": "./dist/public/schema-version.d.ts",
+      "default": "./dist/public/schema-version.js"
+    },
     "./operational-artifacts": {
       "types": "./dist/public/operational-artifacts.d.ts",
       "default": "./dist/public/operational-artifacts.js"
+    },
+    "./ignore-policy": {
+      "types": "./dist/public/ignore-policy.d.ts",
+      "import": "./dist/public/ignore-policy.js",
+      "default": "./dist/public/ignore-policy.js"
     }
   },
   "types": "./dist/cli.d.ts",
@@ -92,8 +101,9 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.5.2",
-    "ts-morph": "^23.0.0"
+    "kibi-core": "^0.5.3",
+    "ts-morph": "^23.0.0",
+    "ignore": "^5.3.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/schema/config.json

@@ -186,6 +186,11 @@
               "type": "boolean",
               "description": "Detect requirements with incomplete strict subject/property fact pairing for contradiction-safe semantics",
               "default": false
+            },
+            "strict-readiness": {
+              "type": "boolean",
+              "description": "Report strict contradiction-readiness levels for requirements that are still prose-only or otherwise not contradiction-ready",
+              "default": false
             }
           },
           "additionalProperties": false
@@ -229,7 +234,9 @@
           "required-fields": true,
           "deprecated-adr-no-successor": true,
           "domain-contradictions": true,
-          "strict-fact-shape": false
+          "strict-fact-shape": false,
+          "strict-req-fact-pairing": false,
+          "strict-readiness": false
         },
         "symbolTraceability": {
           "requireAdr": false

package/src/public/check-types.ts

@@ -17,7 +17,7 @@
  */
 
 /**
- * Public re-export barrel for shared check types.
+ * Public re-export barrel for shared check types and MCP-consumed modeling helpers.
  * Import from "kibi-cli/public/check-types" in MCP or external consumers.
  */
 export type {
@@ -26,6 +26,12 @@ export type {
   SymbolTraceabilityOptions,
   Violation,
 } from "../utils/rule-registry.js";
+export type {
+  SemanticClaim,
+  StableRequirementIds,
+  StrictModelInput,
+  StrictWriteSet,
+} from "../utils/strict-modeling.js";
 
 export {
   DEFAULT_CHECKS_CONFIG,
@@ -35,3 +41,11 @@ export {
   mergeChecksConfig,
   validateRuleName,
 } from "../utils/rule-registry.js";
+
+export {
+  buildStableRequirementIds,
+  buildStrictWriteSet,
+  modelRequirementClaims,
+  normalizePropertyKey,
+  normalizeSubjectKey,
+} from "../utils/strict-modeling.js";

package/src/public/extractors/manifest.ts

@@ -19,6 +19,8 @@
 export {
   extractFromManifest,
   extractFromManifestString,
+  readManifestWithCoordinateOverlay,
   type ExtractionResult,
   type ManifestError,
+  type ManifestSymbolRecord,
 } from "../../extractors/manifest.js";

package/src/public/ignore-policy.ts

@@ -0,0 +1,229 @@
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import * as path from "node:path";
+import ignore from "ignore";
+
+const HARD_DENYLIST = [
+  ".kb",
+  ".git",
+  "node_modules",
+  "vendor",
+  "third_party",
+  ".sisyphus",
+  ".opencode",
+];
+
+export interface IgnorePolicy {
+  isIgnored(inputPath: string): boolean;
+  getFastGlobIgnoreGlobs(): string[];
+  explain(inputPath: string): { ignored: boolean; reason?: string };
+}
+
+function readIgnoreFileLines(filePath: string): string[] {
+  if (!existsSync(filePath)) return [];
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return content
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0 && !l.startsWith("#"));
+  } catch {
+    return [];
+  }
+}
+
+function toPosix(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+// implements REQ-001
+export function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy {
+  const root = path.resolve(workspaceRoot);
+
+  // Load root .gitignore
+  const rootGitignorePath = path.join(root, ".gitignore");
+  const rootGitPatterns = readIgnoreFileLines(rootGitignorePath);
+
+  // Load .git/info/exclude
+  const gitInfoExcludePath = path.join(root, ".git", "info", "exclude");
+  const gitInfoPatterns = readIgnoreFileLines(gitInfoExcludePath);
+
+  // Find nested .gitignore files (skip scanning inside hard denylist directories)
+  const nestedPatterns = new Map<string, string[]>();
+
+  function walk(dirAbs: string) {
+    let entries;
+    try {
+      entries = readdirSync(dirAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const name = String(ent.name);
+      const abs = path.join(dirAbs, name);
+      if (ent.isDirectory()) {
+        // avoid descending into common heavy or control directories
+        if (HARD_DENYLIST.includes(name)) continue;
+        // also avoid .git itself to prevent reading internal excludes as nested
+        if (name === ".git") continue;
+        walk(abs);
+      } else if (ent.isFile()) {
+        if (name === ".gitignore") {
+          // skip root .gitignore (we already loaded it)
+          if (path.resolve(dirAbs) === root) continue;
+          const patterns = readIgnoreFileLines(abs);
+          const relDir = path.relative(root, dirAbs) || ".";
+          nestedPatterns.set(toPosix(relDir), patterns);
+        }
+      }
+    }
+  }
+
+  walk(root);
+
+  // Create ignore instances
+  const rootIgnore = ignore();
+  if (rootGitPatterns.length > 0) rootIgnore.add(rootGitPatterns);
+
+  const gitInfoIgnore = ignore();
+  if (gitInfoPatterns.length > 0) gitInfoIgnore.add(gitInfoPatterns);
+
+  const nestedIgnoreMap = new Map<string, ReturnType<typeof ignore>>();
+  for (const [dirRel, pats] of nestedPatterns.entries()) {
+    const ig = ignore();
+    if (pats.length > 0) ig.add(pats);
+    nestedIgnoreMap.set(dirRel, ig);
+  }
+
+  // Prepare nested directories sorted by specificity (longest first)
+  const nestedDirsSorted = Array.from(nestedIgnoreMap.keys()).sort((a, b) => b.length - a.length);
+
+  function isPathOutsideWorkspace(absPath: string): boolean {
+    const rel = path.relative(root, absPath);
+    // path.relative returns paths starting with '..' for outside
+    return rel === "" ? false : rel.split(path.sep)[0] === "..";
+  }
+
+  function matchesHardDeny(relPosix: string): boolean {
+    const segments = relPosix.split("/").filter(Boolean);
+    for (const deny of HARD_DENYLIST) {
+      if (segments.includes(deny)) return true;
+    }
+    return false;
+  }
+
+  function isIgnoredInternal(inputPath: string): { ignored: boolean; reason?: string } {
+    // Resolve to absolute and relative path inside workspace
+    const abs = path.isAbsolute(inputPath) ? path.resolve(inputPath) : path.resolve(root, inputPath);
+
+    if (path.isAbsolute(inputPath) && isPathOutsideWorkspace(abs)) {
+      return { ignored: true, reason: "outside_workspace" };
+    }
+
+    const rel = path.relative(root, abs) || ".";
+    const relPosix = toPosix(rel);
+
+    // Hard denylist always wins
+    if (matchesHardDeny(relPosix)) return { ignored: true, reason: "hard_deny" };
+
+    // Root .gitignore
+    try {
+      if (rootGitPatterns.length > 0 && rootIgnore.ignores(relPosix)) {
+        return { ignored: true, reason: "gitignored" };
+      }
+    } catch (e) {
+      // ignore errors from library usage; continue
+    }
+
+    // .git/info/exclude
+    try {
+      if (gitInfoPatterns.length > 0 && gitInfoIgnore.ignores(relPosix)) {
+        return { ignored: true, reason: "git_info_exclude" };
+      }
+    } catch (e) {
+      // noop
+    }
+
+    // Nested .gitignore (apply relative to their directory)
+    for (const dirRel of nestedDirsSorted) {
+      // dirRel is '.' for nested at root which we skipped, so dirRel will be like 'docs'
+      if (dirRel === ".") continue;
+      if (relPosix === dirRel || relPosix.startsWith(dirRel + "/")) {
+        const sub = relPosix === dirRel ? "." : relPosix.slice(dirRel.length + 1);
+        const ig = nestedIgnoreMap.get(dirRel)!;
+        try {
+          if (ig && ig.ignores(sub)) return { ignored: true, reason: "gitignored" };
+        } catch (e) {
+          // noop
+        }
+      }
+    }
+
+    return { ignored: false };
+  }
+
+  function getFastGlobIgnoreGlobs(): string[] {
+    const globs: string[] = [];
+
+    // Hard denylist globs
+    for (const d of HARD_DENYLIST) {
+      // match directory and its contents anywhere
+      globs.push(`**/${d}/**`);
+      globs.push(`**/${d}`);
+    }
+
+    // Root .gitignore patterns (convert to simple globs)
+    for (const p of rootGitPatterns) {
+      if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+      let pat = p;
+      if (pat.startsWith("/")) pat = pat.slice(1);
+      if (pat.includes("/")) {
+        // anchored path
+        globs.push(`**/${toPosix(pat)}`);
+      } else {
+        globs.push(`**/${pat}`);
+      }
+    }
+
+    // .git/info/exclude patterns
+    for (const p of gitInfoPatterns) {
+      if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+      let pat = p;
+      if (pat.startsWith("/")) pat = pat.slice(1);
+      if (pat.includes("/")) {
+        globs.push(`**/${toPosix(pat)}`);
+      } else {
+        globs.push(`**/${pat}`);
+      }
+    }
+
+    // Nested .gitignore patterns - prefix with directory path
+    // Use the raw patterns collected in nestedPatterns so we scope patterns
+    // to the nested directory instead of ignoring the entire directory.
+    // Debug: print nested patterns and the computed globs to help diagnosing test failures.
+    for (const [dirRel, patterns] of nestedPatterns.entries()) {
+      for (const p of patterns) {
+        if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+        let pat = p;
+        if (pat.startsWith("/")) pat = pat.slice(1);
+        const prefix = dirRel === "." ? "" : `${dirRel}/`;
+        if (pat.includes("/")) {
+          globs.push(`**/${prefix}${toPosix(pat)}`);
+        } else {
+          globs.push(`**/${prefix}${pat}`);
+        }
+      }
+    }
+
+    return Array.from(new Set(globs));
+  }
+
+  return {
+    isIgnored(inputPath: string) {
+      return isIgnoredInternal(inputPath).ignored;
+    },
+    getFastGlobIgnoreGlobs,
+    explain(inputPath: string) {
+      return isIgnoredInternal(inputPath);
+    },
+  };
+}