kibi-cli 0.16.1 → 0.18.1

package/dist/public/operations/legacy-migration-plan.js

@@ -0,0 +1,409 @@
+import { createHash } from "node:crypto";
+import { requirementSemanticText } from "../../extractors/markdown.js";
+import { buildSuggestion } from "../../operations/modeling/predicate-applyplan.js";
+import { BUILT_IN_PREDICATE_SCHEMAS } from "../../operations/modeling/predicate-catalog.js";
+import { inferSubject } from "../../operations/modeling/predicate-inference.js";
+import { loadExistingPredicateSchemas } from "../../operations/modeling/predicate-loader.js";
+import { scoreSchema } from "../../operations/modeling/predicate-ranker.js";
+import { analyzeSemanticAdvisorInput } from "../../operations/semantic-advisor/analyze-prose.js";
+import { semanticSourceHash } from "../../operations/semantic-advisor/shared.js";
+import { loadMarkdownBody } from "../../search-ranking.js";
+import { loadEntities } from "./discovery-entities.js";
+export const LEGACY_MIGRATION_PLAN_VERSION = "kibi.legacy-migration-plan.v1";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringList(value) {
+    if (typeof value === "string")
+        return [stripKbEntityPrefix(value)];
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => typeof item === "string" ? [stripKbEntityPrefix(item)] : []);
+}
+function stripKbEntityPrefix(value) {
+    return value.replace(/^kb:entity\//, "");
+}
+function clampInteger(value, fallback, minimum, maximum) {
+    if (!Number.isInteger(value))
+        return fallback;
+    return Math.min(maximum, Math.max(minimum, value ?? fallback));
+}
+function clampScore(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 0.35;
+    return Math.min(1, Math.max(0, value));
+}
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, stableValue(item)]));
+}
+function stableStringify(value) {
+    return JSON.stringify(stableValue(value));
+}
+function hash(value) {
+    return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+function migrationRepairBatches(plan) {
+    const seen = new Set();
+    return plan.batches
+        .filter((batch) => batch.phase === "semantic_inventory" && batch.state === "ready")
+        .filter((batch) => {
+        if (seen.has(batch.requirementId))
+            return false;
+        seen.add(batch.requirementId);
+        return true;
+    })
+        .sort((left, right) => left.requirementId.localeCompare(right.requirementId));
+}
+function schemaIdentity(schema) {
+    return `${schema.predicate_name}(${schema.argument_names.join(",")}):${schema.argument_types.join(",")}`;
+}
+function predicateCatalog(projectSchemas) {
+    const result = [];
+    const seen = new Set();
+    for (const [origin, schemas] of [
+        ["project_local", projectSchemas],
+        ["built_in", BUILT_IN_PREDICATE_SCHEMAS],
+    ]) {
+        for (const schema of schemas) {
+            const identity = schemaIdentity(schema);
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            result.push({ schema, origin });
+        }
+    }
+    return result;
+}
+function rankPredicateCandidates(claimText, catalog, limit, minimumScore) {
+    const subject = inferSubject(claimText, undefined);
+    return catalog
+        .map(({ schema, origin }) => ({
+        schema,
+        origin,
+        score: scoreSchema(schema, claimText),
+    }))
+        .filter(({ score }) => score >= minimumScore)
+        .sort((left, right) => right.score - left.score ||
+        (left.origin === right.origin
+            ? 0
+            : left.origin === "project_local"
+                ? -1
+                : 1) ||
+        left.schema.predicate_name.localeCompare(right.schema.predicate_name) ||
+        left.schema.id.localeCompare(right.schema.id))
+        .slice(0, limit)
+        .map(({ schema, origin, score }) => {
+        const suggestion = buildSuggestion(schema, claimText, subject, score);
+        return {
+            schemaId: schema.id,
+            origin,
+            predicateName: schema.predicate_name,
+            argumentNames: [...schema.argument_names],
+            argumentTypes: [...schema.argument_types],
+            score,
+            bindingStatus: suggestion.binding_status,
+            unboundArguments: [...suggestion.unbound_arguments],
+            polarity: suggestion.polarity,
+            canonicalKey: suggestion.canonical_key,
+            writeEligible: false,
+        };
+    });
+}
+function propositionDisposition(proposition, suggestion, candidates) {
+    if (proposition.status === "nonlogical") {
+        return { recommendedLane: "nonlogical", disposition: "nonlogical" };
+    }
+    if (suggestion?.kind === "strict_property") {
+        return {
+            recommendedLane: "strict_property",
+            disposition: "strict_property_candidate",
+        };
+    }
+    if (suggestion?.kind === "rule") {
+        return { recommendedLane: "rule", disposition: "rule_candidate" };
+    }
+    if (suggestion?.kind === "predicate" || candidates.length > 0) {
+        return {
+            recommendedLane: "predicate",
+            disposition: "predicate_candidate",
+        };
+    }
+    if (proposition.status === "ambiguous" ||
+        suggestion?.kind === "ambiguity_observation") {
+        return {
+            recommendedLane: "unresolved",
+            disposition: "unresolved_ambiguity",
+        };
+    }
+    return {
+        recommendedLane: "unresolved",
+        disposition: "unresolved_ontology_gap",
+    };
+}
+function claimDelta(existing, expected) {
+    const existingSet = new Set(existing);
+    const expectedSet = new Set(expected);
+    return {
+        preserved: expected.filter((claim) => existingSet.has(claim)).sort(),
+        added: expected.filter((claim) => !existingSet.has(claim)).sort(),
+        stale: existing.filter((claim) => !expectedSet.has(claim)).sort(),
+    };
+}
+async function buildBatch(repairBatch, requirement, readSource, catalog, predicateLimit, predicateMinScore) {
+    const requirementId = repairBatch.requirementId;
+    const sourceFile = typeof requirement?.source === "string" ? requirement.source : null;
+    const sourceText = requirement ? await readSource(requirement) : null;
+    const existingTextRef = typeof requirement?.text_ref === "string" && requirement.text_ref.trim()
+        ? requirement.text_ref.trim()
+        : null;
+    const existingSemanticText = typeof requirement?.semantic_text === "string" &&
+        requirement.semantic_text.trim()
+        ? requirement.semantic_text.trim()
+        : null;
+    const sourceHash = sourceText ? semanticSourceHash(sourceText) : null;
+    const sourceMissing = requirement === undefined || !sourceText;
+    const sourceConflict = !sourceMissing &&
+        existingSemanticText !== null &&
+        existingSemanticText !== sourceText;
+    const sourceStatus = sourceMissing
+        ? "missing"
+        : sourceConflict
+            ? "conflict"
+            : "compatible";
+    const diagnostics = [];
+    if (requirement === undefined) {
+        diagnostics.push(`Requirement ${requirementId} is present in the repair plan but absent from exact KB query results.`);
+    }
+    else if (!sourceText) {
+        diagnostics.push(`Requirement ${requirementId} has no readable authored Markdown body inside the workspace.`);
+    }
+    else if (sourceConflict) {
+        diagnostics.push(`Requirement ${requirementId} has semantic_text that differs from its normalized authored Markdown body; review the source drift before applying this migration.`);
+    }
+    if (!requirement || !sourceText || !sourceHash) {
+        return {
+            id: `legacy-migration-${requirementId}`,
+            requirementId,
+            repairBatchId: repairBatch.id,
+            dependsOn: [...repairBatch.dependsOn],
+            state: "blocked",
+            autoApplicable: false,
+            sourceBinding: {
+                status: sourceStatus,
+                sourceFile,
+                sourceKind: "authored_markdown_body",
+                sourceHash,
+                sourceByteLength: sourceText
+                    ? Buffer.byteLength(sourceText, "utf8")
+                    : 0,
+                persistedField: null,
+                existingTextRef,
+                existingSemanticText,
+                reason: diagnostics[0] ?? "Authored requirement source is unavailable.",
+            },
+            sourceText,
+            claimDelta: { preserved: [], added: [], stale: [] },
+            propositions: [],
+            requirementPropertyPatchPreview: null,
+            diagnostics,
+        };
+    }
+    const existingLogicClaims = stringList(requirement.logic_claims);
+    const analysis = analyzeSemanticAdvisorInput({
+        payload: {
+            type: "req",
+            id: requirementId,
+            properties: {
+                title: requirement.title,
+                status: requirement.status,
+                source: sourceFile ?? undefined,
+                semantic_text: sourceText,
+                logic_claims: existingLogicClaims,
+            },
+            relationships: [],
+        },
+    });
+    const suggestions = new Map(analysis.receipt.suggestions.map((suggestion) => [
+        suggestion.claim_key,
+        suggestion,
+    ]));
+    const propositions = analysis.receipt.propositions.map((proposition) => {
+        const predicateCandidates = proposition.status === "nonlogical"
+            ? []
+            : rankPredicateCandidates(proposition.claim_text, catalog, predicateLimit, predicateMinScore);
+        const disposition = propositionDisposition(proposition, suggestions.get(proposition.claim_key), predicateCandidates);
+        return {
+            claimKey: proposition.claim_key,
+            claimText: proposition.claim_text,
+            role: proposition.role,
+            inventoryStatus: proposition.status,
+            span: { ...proposition.span },
+            ...disposition,
+            predicateCandidates,
+            reviewRequired: true,
+        };
+    });
+    const expectedClaimKeys = [
+        ...analysis.receipt.logic_coverage.expected_claim_keys,
+    ];
+    const propertyPatch = sourceConflict
+        ? null
+        : {
+            semantic_text: sourceText,
+            logic_claims: expectedClaimKeys,
+            semantic_clauses: analysis.receipt.clauses.map((clause) => clause.text),
+            semantic_inventory_version: analysis.receipt.inventory_contract.version,
+            semantic_source_field: analysis.receipt.inventory_contract.source_field,
+            semantic_source_hash: analysis.receipt.inventory_contract.source_hash,
+            semantic_inventory: analysis.receipt.propositions.map((proposition) => ({
+                claim_key: proposition.claim_key,
+                claim_text: proposition.claim_text,
+                role: proposition.role,
+                status: proposition.status,
+                span: { ...proposition.span },
+                ...(proposition.reason ? { reason: proposition.reason } : {}),
+            })),
+        };
+    return {
+        id: `legacy-migration-${requirementId}`,
+        requirementId,
+        repairBatchId: repairBatch.id,
+        dependsOn: [...repairBatch.dependsOn],
+        state: sourceConflict ? "blocked" : "ready_for_review",
+        autoApplicable: false,
+        sourceBinding: {
+            status: sourceStatus,
+            sourceFile,
+            sourceKind: "authored_markdown_body",
+            sourceHash,
+            sourceByteLength: Buffer.byteLength(sourceText, "utf8"),
+            persistedField: sourceConflict ? null : "semantic_text",
+            existingTextRef,
+            existingSemanticText,
+            reason: sourceConflict
+                ? (diagnostics[0] ?? "Existing semantic_text has drifted from source.")
+                : existingTextRef
+                    ? "Authored Markdown can be reviewed in semantic_text while preserving the independent text_ref evidence."
+                    : "Authored Markdown can be reviewed in the dedicated semantic_text field.",
+        },
+        sourceText,
+        claimDelta: claimDelta(existingLogicClaims, expectedClaimKeys),
+        propositions,
+        requirementPropertyPatchPreview: propertyPatch,
+        diagnostics: [...diagnostics, ...analysis.warnings],
+    };
+}
+// implements REQ-kibi-legacy-migration-preview-v2
+export async function buildLegacyMigrationPlan(repairPlan, input, codeSnapshot, dependencies) {
+    const offset = clampInteger(input.migrationOffset, 0, 0, Number.MAX_SAFE_INTEGER);
+    const limit = clampInteger(input.migrationLimit, 1, 1, 10);
+    const predicateLimit = clampInteger(input.migrationPredicateLimit, 5, 1, 20);
+    const predicateMinScore = clampScore(input.migrationPredicateMinScore);
+    const candidateBatches = migrationRepairBatches(repairPlan);
+    const selected = candidateBatches.slice(offset, offset + limit);
+    const requirementById = new Map(dependencies.requirements.flatMap((requirement) => typeof requirement.id === "string"
+        ? [[requirement.id, requirement]]
+        : []));
+    const catalog = predicateCatalog(dependencies.projectPredicateSchemas);
+    const predicateCatalogHash = hash(catalog.map(({ schema, origin }) => ({ origin, schema })));
+    const batches = [];
+    for (const repairBatch of selected) {
+        batches.push(await buildBatch(repairBatch, requirementById.get(repairBatch.requirementId), dependencies.readSource, catalog, predicateLimit, predicateMinScore));
+    }
+    const readyBatchCount = batches.filter((batch) => batch.state === "ready_for_review").length;
+    const blockedBatchCount = batches.length - readyBatchCount;
+    const propositionCount = batches.reduce((count, batch) => count + batch.propositions.length, 0);
+    const assertivePropositionCount = batches.reduce((count, batch) => count +
+        batch.propositions.filter((proposition) => proposition.disposition !== "nonlogical").length, 0);
+    const unresolvedPropositionCount = batches.reduce((count, batch) => count +
+        batch.propositions.filter((proposition) => proposition.disposition.startsWith("unresolved_")).length, 0);
+    const predicateCandidateCount = batches.reduce((count, batch) => count +
+        batch.propositions.reduce((subtotal, proposition) => subtotal + proposition.predicateCandidates.length, 0), 0);
+    const nextOffset = offset + selected.length < candidateBatches.length
+        ? offset + selected.length
+        : null;
+    const diagnostics = [...(dependencies.diagnostics ?? [])];
+    if (!repairPlan.scope.complete) {
+        diagnostics.push("Legacy migration scope is partial because requirement coverage omitted actionable requirements; rerun complete coverage before treating this as a project inventory.");
+    }
+    if (candidateBatches.length > 0 && selected.length === 0) {
+        diagnostics.push(`Migration offset ${offset} is beyond ${candidateBatches.length} ready semantic-inventory requirement batch(es).`);
+    }
+    const planCore = {
+        version: LEGACY_MIGRATION_PLAN_VERSION,
+        codeSnapshot,
+        repairPlanId: repairPlan.planId,
+        predicateCatalogHash,
+        scope: {
+            repairPlanComplete: repairPlan.scope.complete,
+            candidateRequirements: candidateBatches.length,
+            selectedRequirements: selected.length,
+            offset,
+            limit,
+            selectionComplete: offset === 0 && selected.length === candidateBatches.length,
+            nextOffset,
+        },
+        batches,
+    };
+    const planId = `legacy-migration-plan-${hash(planCore).slice(0, 24)}`;
+    const status = !repairPlan.scope.complete
+        ? "partial"
+        : candidateBatches.length === 0
+            ? "no_candidates"
+            : readyBatchCount === 0
+                ? "blocked"
+                : "ready";
+    return {
+        ...planCore,
+        planId,
+        readOnly: true,
+        status,
+        applicationPolicy: {
+            previewOnly: true,
+            reviewEveryProposition: true,
+            preserveExistingTextRefs: true,
+            exactBindingsBeforeWrite: true,
+            validateBeforeEachWrite: true,
+            sequentialUpsertsOnly: true,
+            recheckContradictionsAfterEachBatch: true,
+        },
+        summary: {
+            batchCount: batches.length,
+            readyBatchCount,
+            blockedBatchCount,
+            propositionCount,
+            assertivePropositionCount,
+            unresolvedPropositionCount,
+            predicateCandidateCount,
+        },
+        diagnostics,
+    };
+}
+// implements REQ-kibi-legacy-migration-preview-v2
+export async function buildLegacyMigrationPlanFromContext(repairPlan, input, codeSnapshot, context) {
+    if (!context.prolog) {
+        throw new Error("Legacy migration planning requires a Prolog context");
+    }
+    const requirements = await loadEntities(context.prolog, { type: "req" });
+    const schemaDiagnostics = [];
+    const projectPredicateSchemas = await loadExistingPredicateSchemas(context.prolog, true, schemaDiagnostics);
+    return buildLegacyMigrationPlan(repairPlan, input, codeSnapshot, {
+        requirements,
+        projectPredicateSchemas,
+        diagnostics: schemaDiagnostics,
+        readSource: async (requirement) => {
+            const source = typeof requirement.source === "string" ? requirement.source : "";
+            const body = await loadMarkdownBody(source, context.workspaceRoot);
+            if (body === null)
+                return null;
+            const semanticText = requirementSemanticText(body);
+            return semanticText || null;
+        },
+    });
+}

package/dist/public/operations/node-ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../../src/public/operations/node-ports.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE/E,KAAK,kBAAkB,GAAG,cAAc,GAAG;IACzC,QAAQ,CAAC,IAAI,EAAE,CACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,WAAW,GAAG,OAAO,GAAG;IAC3B,QAAQ,CAAC,YAAY,EAAE,CACrB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,KACrB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AAiBF,eAAO,MAAM,cAAc,EAAE,kBAkB5B,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAgBrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAEzB,CAAC"}
+{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../../src/public/operations/node-ports.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE/E,KAAK,kBAAkB,GAAG,cAAc,GAAG;IACzC,QAAQ,CAAC,IAAI,EAAE,CACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,WAAW,GAAG,OAAO,GAAG;IAC3B,QAAQ,CAAC,YAAY,EAAE,CACrB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,KACrB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AA2HF,eAAO,MAAM,cAAc,EAAE,kBAkB5B,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAiBrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAEzB,CAAC"}

package/dist/public/operations/node-ports.js

@@ -1,9 +1,12 @@
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
+import path from "node:path";
 import { promisify } from "node:util";
 import fg from "fast-glob";
 import { createRepoIgnorePolicy } from "../ignore-policy.js";
 const execFileAsync = promisify(execFile);
+const SNAPSHOT_EXCLUDED_PREFIXES = [".changeset/", ".kb/", "docs/"];
 const ALWAYS_IGNORED_GLOBS = [
     "**/.git/**",
     "**/.kb/**",
@@ -17,6 +20,92 @@ const ALWAYS_IGNORED_GLOBS = [
     "**/coverage/**",
     "**/target/**",
 ];
+function includedSnapshotPath(relativePath) {
+    return !SNAPSHOT_EXCLUDED_PREFIXES.some((prefix) => relativePath === prefix.slice(0, -1) || relativePath.startsWith(prefix));
+}
+function withoutVerificationReceiptFrontmatter(content) {
+    const lines = content.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    if (lines[0]?.trim() !== "---")
+        return content;
+    let inFrontmatter = true;
+    let skippingReceipts = false;
+    const retained = [];
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        if (index > 0 && inFrontmatter && trimmed === "---") {
+            inFrontmatter = false;
+            skippingReceipts = false;
+            retained.push(line);
+            continue;
+        }
+        if (inFrontmatter && /^verification_receipts\s*:/.test(line)) {
+            skippingReceipts = true;
+            continue;
+        }
+        if (inFrontmatter &&
+            skippingReceipts &&
+            /^[A-Za-z_][A-Za-z0-9_-]*\s*:/.test(line)) {
+            skippingReceipts = false;
+        }
+        if (!skippingReceipts)
+            retained.push(line);
+    }
+    return retained.join("");
+}
+function snapshotFileContent(relativePath, content) {
+    if (relativePath.startsWith("documentation/") &&
+        relativePath.endsWith(".md")) {
+        return Buffer.from(withoutVerificationReceiptFrontmatter(content.toString("utf8")));
+    }
+    return content;
+}
+async function workspaceSnapshot(workspaceRoot) {
+    const { stdout: listed } = await execFileAsync("git", [
+        "-C",
+        workspaceRoot,
+        "ls-files",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "-z",
+    ], { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 });
+    const paths = listed
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean)
+        .filter(includedSnapshotPath)
+        .sort();
+    const digest = createHash("sha256");
+    digest.update("kibi.workspace-snapshot.v1\0");
+    for (const relativePath of paths) {
+        digest.update(relativePath);
+        digest.update("\0");
+        try {
+            const content = await fs.readFile(path.join(workspaceRoot, relativePath));
+            digest.update(snapshotFileContent(relativePath, content));
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error
+                ? String(error.code)
+                : "unreadable";
+            digest.update(`<${code}>`);
+        }
+        digest.update("\0");
+    }
+    const { stdout: status } = await execFileAsync("git", [
+        "-C",
+        workspaceRoot,
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=normal",
+    ], { maxBuffer: 16 * 1024 * 1024 });
+    return {
+        version: "kibi.workspace-snapshot.v1",
+        hash: digest.digest("hex"),
+        dirty: status.trim().length > 0,
+        fileCount: paths.length,
+    };
+}
 export const nodeFilesystem = {
     readFile: (filePath) => fs.readFile(filePath, "utf8"),
     writeFile: async (filePath, data) => {
@@ -47,6 +136,7 @@ export const nodeGit = {
         ]);
         return stdout.trim();
     },
+    workspaceSnapshot,
     ignoredPaths: async (workspaceRoot, paths) => {
         const policy = createRepoIgnorePolicy(workspaceRoot);
         return paths.filter((candidate) => policy.isIgnored(candidate));