frontend-harness 0.7.10 → 0.8.0

package/dist/runtime/knowledge/core.js

@@ -3,7 +3,14 @@ import path from "node:path";
 import { isDirectoryWithoutSymlink, isRegularFileWithoutSymlink, writeJson, writeText } from "../../storage/json.js";
 import { harnessPath, relativeHarnessPath } from "../../storage/paths.js";
 import { normalizeProjectRelativePath } from "../project-paths.js";
+import { showIngestRecord } from "../ingest.js";
 import { kindTypeMap, knowledgeKinds, knowledgeStabilities, knowledgeStatuses, knowledgeTypes, MAX_KNOWLEDGE_DIRECTORY_DEPTH, MAX_KNOWLEDGE_MARKDOWN_BYTES, MAX_KNOWLEDGE_MARKDOWN_FILES } from "./constants.js";
+export const MAX_KNOWLEDGE_LIST_CARDS = 20;
+export const MAX_KNOWLEDGE_SEARCH_RESULTS = 8;
+export const MAX_KNOWLEDGE_DRAFT_UPDATE_CANDIDATES = 8;
+export const MAX_KNOWLEDGE_INDEX_CARDS = 20;
+export const MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS = 20;
+const MAX_KNOWLEDGE_REFERENCE_SUGGESTIONS = 20;
 export function promoteKnowledge(projectRoot, input) {
     const title = input.title?.trim();
     const body = input.body?.trim();
@@ -121,11 +128,13 @@ export function addKnowledge(projectRoot, input) {
     const contentFields = atomicContentFields(kind, input);
     const inputSummary = input.summary?.trim();
     const contentSummary = inputSummary || summarizeAtomicContent(kind, subject, contentFields);
+    const sourcePaths = parseKnowledgeSourcePaths(input.source, "knowledge add --source");
+    const type = typeForAtomicKnowledge(kind, sourcePaths);
     const rendered = renderAtomicKnowledge({
         id,
         title,
         summary: contentSummary,
-        type: kindTypeMap[kind],
+        type,
         kind,
         subject,
         status,
@@ -133,7 +142,7 @@ export function addKnowledge(projectRoot, input) {
         createdAt,
         scope: splitList(input.scope),
         tags: splitList(input.tags),
-        sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge add --source"),
+        sourcePaths,
         verification: splitList(input.verification),
         coverage: splitList(input.coverage),
         prdAnchors: splitList(input.anchor),
@@ -144,12 +153,184 @@ export function addKnowledge(projectRoot, input) {
         path: relativePath,
         id,
         title,
-        type: kindTypeMap[kind],
+        type,
         status,
         stability,
         createdAt
     };
 }
+export function draftKnowledgeFromIngest(projectRoot, input) {
+    if (!input.ref?.trim()) {
+        throw new Error("knowledge draft requires --ref ingest://<kind>/<source-id>");
+    }
+    const record = showIngestRecord(projectRoot, input.ref);
+    const recommendedKind = recommendedKnowledgeKind(record.kind);
+    const recommendedType = typeForAtomicKnowledge(recommendedKind, [record.ingestRef]);
+    const subject = draftSubject(record);
+    const id = slugify(`${subject}-${recommendedKind}`) || `${record.id}-${recommendedKind}`;
+    const defaults = {
+        id,
+        kind: recommendedKind,
+        subject,
+        summary: record.summary,
+        source: record.ingestRef,
+        coverage: draftCoveragePlaceholder(record.kind),
+        verification: draftVerificationPlaceholder(record.kind),
+        scope: draftScope(record),
+        tags: draftTags(record.kind)
+    };
+    const contentFlag = contentFlagForKind(recommendedKind);
+    const updateCandidateSelection = draftUpdateCandidates(projectRoot, record, defaults);
+    const updateCandidates = updateCandidateSelection.candidates;
+    const args = [
+        "knowledge",
+        "add",
+        "--json",
+        "--id",
+        defaults.id,
+        "--kind",
+        defaults.kind,
+        "--subject",
+        defaults.subject,
+        "--summary",
+        defaults.summary,
+        `--${contentFlag}`,
+        `<atomic ${contentFlag} distilled from ${record.ingestRef}>`,
+        "--source",
+        defaults.source,
+        "--coverage",
+        defaults.coverage,
+        "--verification",
+        defaults.verification,
+        "--scope",
+        defaults.scope,
+        "--tags",
+        defaults.tags
+    ];
+    return {
+        contractVersion: 1,
+        ingestRef: record.ingestRef,
+        ingestKind: record.kind,
+        source: record.source.value,
+        summary: record.summary,
+        recommendedKind,
+        recommendedType,
+        recommendedAction: updateCandidates.length > 0 ? "update" : "add",
+        command: "frontend-harness knowledge add --json",
+        args,
+        updateCandidates,
+        limits: {
+            updateCandidates: updateCandidateSelection.limits
+        },
+        requiredEdits: [
+            ...(updateCandidateSelection.limits.total > 0
+                ? ["Prefer a matching update candidate before adding a new card for the same source."]
+                : []),
+            `Replace --${contentFlag} with one atomic durable fact; create separate cards for separate facts.`,
+            "Replace --coverage with the precise source section, endpoint, screen, or acceptance block.",
+            "Replace --verification with the concrete check or evidence that proves the fact still holds.",
+            "Narrow --scope and --tags so future context selection can find the card without broad matching."
+        ],
+        defaults
+    };
+}
+function draftUpdateCandidates(projectRoot, record, defaults) {
+    const producedIds = new Set(record.producedKnowledgeCardIds);
+    const cards = discoverKnowledgeCards(projectRoot);
+    const matches = cards
+        .filter((card) => producedIds.has(card.id) || card.sourcePaths.some((sourcePath) => sameKnowledgeSourceReference(sourcePath, record.ingestRef) || sameKnowledgeSourceReference(sourcePath, record.source.value)))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const selected = matches
+        .slice(0, MAX_KNOWLEDGE_DRAFT_UPDATE_CANDIDATES)
+        .map((card) => ({
+        id: card.id,
+        path: card.path,
+        title: card.title,
+        summary: card.summary,
+        sourcePaths: card.sourcePaths,
+        command: "frontend-harness knowledge update --json",
+        args: [
+            "knowledge",
+            "update",
+            "--json",
+            "--id",
+            card.id,
+            "--summary",
+            defaults.summary,
+            "--source",
+            defaults.source,
+            "--coverage",
+            defaults.coverage,
+            "--verification",
+            defaults.verification,
+            "--scope",
+            defaults.scope,
+            "--tags",
+            defaults.tags
+        ]
+    }));
+    return {
+        candidates: selected,
+        limits: {
+            selected: selected.length,
+            total: matches.length,
+            omitted: Math.max(0, matches.length - selected.length)
+        }
+    };
+}
+function recommendedKnowledgeKind(kind) {
+    if (kind === "openapi") {
+        return "workflow";
+    }
+    return "rule";
+}
+function typeForAtomicKnowledge(kind, sourcePaths) {
+    if (sourcePaths.some(isApiContractSourcePath)) {
+        return "api_contract";
+    }
+    return kindTypeMap[kind];
+}
+function isApiContractSourcePath(sourcePath) {
+    const normalized = sourcePath.replace(/\\/g, "/");
+    if (/^ingest:\/\/openapi\//i.test(normalized)) {
+        return isIngestReference(normalized);
+    }
+    if (/(^|\/)(openapi|swagger)(\/|[-_.])/i.test(normalized)) {
+        return true;
+    }
+    return /(^|\/)api\/[^/]+\.(?:json|ya?ml)$/i.test(normalized);
+}
+function draftSubject(record) {
+    const sourceName = path.basename(record.source.value).replace(/\.[^.]+$/, "");
+    const raw = sourceName || record.id;
+    return titleCase(raw.replace(/[-_.]+/g, " ")).trim() || record.id;
+}
+function draftScope(record) {
+    return record.id.replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
+}
+function draftCoveragePlaceholder(kind) {
+    if (kind === "ui-package") {
+        return "<screen, component, state, or visual reference>";
+    }
+    if (kind === "openapi") {
+        return "<endpoint, schema, operation, or contract behavior>";
+    }
+    return "<precise section, endpoint, screen, or acceptance block>";
+}
+function draftVerificationPlaceholder(kind) {
+    if (kind === "ui-package") {
+        return "<visual, responsive, or interaction evidence required>";
+    }
+    if (kind === "openapi") {
+        return "<contract shape check or mocked integration evidence required>";
+    }
+    return "<specific check or evidence required>";
+}
+function draftTags(kind) {
+    return kind === "ui-package"
+        ? "ui-package,ui"
+        : kind.replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
+}
 export function updateKnowledge(projectRoot, input) {
     const target = input.id?.trim() || input.path?.trim();
     if (!target) {
@@ -231,6 +412,7 @@ export function indexKnowledge(projectRoot) {
     const cards = discoverKnowledgeCards(projectRoot);
     const prdSources = summarizePrdSources(projectRoot, cards);
     const moduleSummaries = summarizeModules(cards);
+    const selectedCards = cards.slice(0, MAX_KNOWLEDGE_INDEX_CARDS);
     const result = {
         artifactPath: relativeHarnessPath("knowledge", "index.json"),
         cardCount: cards.length,
@@ -242,7 +424,14 @@ export function indexKnowledge(projectRoot) {
         byKind: countByKind(cards),
         moduleSummaries,
         prdSources,
-        cards: cards.map(stripSearchable)
+        cards: selectedCards.map(stripSearchable),
+        limits: {
+            cards: {
+                selected: selectedCards.length,
+                total: cards.length,
+                omitted: Math.max(0, cards.length - selectedCards.length)
+            }
+        }
     };
     writeJson(path.join(projectRoot, result.artifactPath), result);
     return result;
@@ -270,7 +459,7 @@ export function checkKnowledgeCoverage(projectRoot, options = {}) {
         .filter((source) => source.activeCardCount === 0)
         .map((source) => source.path);
     const missingSourcePaths = [...new Set(cards.flatMap((card) => card.sourcePaths)
-            .filter((sourcePath) => sourcePath && !isExternalReference(sourcePath) && !isKnowledgeSourceFile(projectRoot, sourcePath)))].sort();
+            .filter((sourcePath) => sourcePath && !isExternalReference(sourcePath) && !isResolvedKnowledgeSource(projectRoot, sourcePath)))].sort();
     const cardsWithoutSource = cards
         .filter((card) => card.status === "active" && card.type === "prd_semantics" && card.sourcePaths.length === 0)
         .map((card) => card.path);
@@ -320,15 +509,23 @@ export function listKnowledge(projectRoot, options = {}) {
     const cards = discoverKnowledgeCards(projectRoot)
         .filter((card) => options.includeDeprecated || card.status === "active")
         .map(stripSearchable);
-    return { cards };
+    const selected = cards.slice(0, MAX_KNOWLEDGE_LIST_CARDS);
+    return {
+        cards: selected,
+        limits: {
+            selected: selected.length,
+            total: cards.length,
+            omitted: Math.max(0, cards.length - selected.length)
+        }
+    };
 }
 export function searchKnowledge(projectRoot, query, options = {}) {
     const normalizedQuery = normalize(query ?? "");
     if (!normalizedQuery) {
         throw new Error("knowledge search requires --query");
     }
-    const limit = options.limit && options.limit > 0 ? options.limit : 8;
-    const cards = discoverKnowledgeCards(projectRoot)
+    const limit = options.limit && options.limit > 0 ? options.limit : MAX_KNOWLEDGE_SEARCH_RESULTS;
+    const matches = discoverKnowledgeCards(projectRoot)
         .filter((card) => options.includeDeprecated || card.status === "active")
         .map((card) => ({
         card,
@@ -340,13 +537,22 @@ export function searchKnowledge(projectRoot, query, options = {}) {
             return right.score - left.score;
         }
         return left.card.path.localeCompare(right.card.path);
-    })
+    });
+    const cards = matches
         .slice(0, limit)
         .map(({ card, score }) => ({
         ...stripSearchable(card),
         score
     }));
-    return { query: query ?? "", cards };
+    return {
+        query: query ?? "",
+        cards,
+        limits: {
+            selected: cards.length,
+            total: matches.length,
+            omitted: Math.max(0, matches.length - cards.length)
+        }
+    };
 }
 export function showKnowledge(projectRoot, idOrPath) {
     const target = idOrPath?.trim();
@@ -368,6 +574,9 @@ export function showKnowledge(projectRoot, idOrPath) {
         body: extractMarkdownBody(content)
     };
 }
+function sameKnowledgeSourceReference(left, right) {
+    return left.replace(/\\/g, "/").toLowerCase() === right.replace(/\\/g, "/").toLowerCase();
+}
 export function checkKnowledge(projectRoot) {
     const knowledgeRoot = harnessPath(projectRoot, "knowledge");
     const relativeRoot = path.relative(projectRoot, knowledgeRoot).split(path.sep).join(path.posix.sep);
@@ -431,6 +640,15 @@ export function checkKnowledge(projectRoot) {
             if (contentValue && normalize(contentValue) === normalize(parsed.metadata.summary ?? "")) {
                 warnings.push(`${relativePath} summary duplicates the primary atomic content; use summary for context and the primary field for the durable rule.`);
             }
+            if (parsed.metadata.status === "active" && parsed.metadata.sourcePaths.some((sourcePath) => sourcePath.toLowerCase().startsWith("ingest://"))) {
+                errors.push(...ingestLinkedAtomicMetadataErrors(relativePath, parsed.metadata));
+            }
+            for (const coverage of parsed.metadata.coverage.filter(isDraftPlaceholderCoverage)) {
+                errors.push(`${relativePath} coverage contains an unedited knowledge draft placeholder: ${coverage}.`);
+            }
+            for (const verification of parsed.metadata.verification.filter(isDraftPlaceholderVerification)) {
+                errors.push(`${relativePath} verification contains an unedited knowledge draft placeholder: ${verification}.`);
+            }
             if (parsed.metadata.sourcePaths.some(isPrdSourcePath) && parsed.metadata.coverage.length === 0) {
                 warnings.push(`${relativePath} should include coverage items for PRD block traceability.`);
             }
@@ -442,7 +660,7 @@ export function checkKnowledge(projectRoot) {
             warnings.push(`${relativePath} frontmatter coverage disagrees with body traceability.`);
         }
         for (const sourcePath of parsed.metadata.sourcePaths) {
-            if (sourcePath && !isExternalReference(sourcePath) && !isKnowledgeSourceFile(projectRoot, sourcePath)) {
+            if (sourcePath && !isExternalReference(sourcePath) && !isResolvedKnowledgeSource(projectRoot, sourcePath)) {
                 warnings.push(`${relativePath} source path is missing or unsafe: ${sourcePath}.`);
             }
         }
@@ -546,17 +764,22 @@ function resolveKnowledgeCardReference(cards, target) {
         return idMatches[0] ?? null;
     }
     if (idMatches.length > 1) {
-        throw new Error(`knowledge card reference is ambiguous: ${target}. Use --path with one of: ${idMatches.map((item) => item.path).join(", ")}.`);
+        throw new Error(formatAmbiguousKnowledgeReference(target, idMatches));
     }
     const pathSuffixMatches = cards.filter((item) => item.path.endsWith(`/${target}`));
     if (pathSuffixMatches.length === 1) {
         return pathSuffixMatches[0] ?? null;
     }
     if (pathSuffixMatches.length > 1) {
-        throw new Error(`knowledge card reference is ambiguous: ${target}. Use --path with one of: ${pathSuffixMatches.map((item) => item.path).join(", ")}.`);
+        throw new Error(formatAmbiguousKnowledgeReference(target, pathSuffixMatches));
     }
     return null;
 }
+function formatAmbiguousKnowledgeReference(target, matches) {
+    const selected = matches.slice(0, MAX_KNOWLEDGE_REFERENCE_SUGGESTIONS).map((item) => item.path);
+    const omitted = Math.max(0, matches.length - selected.length);
+    return `knowledge card reference is ambiguous: ${target}. Use --path with one of (selected: ${selected.length}; total: ${matches.length}; omitted: ${omitted}): ${selected.join(", ")}.`;
+}
 function parseKnowledgeFrontmatter(content) {
     const metadata = {
         scope: [],
@@ -932,6 +1155,9 @@ function validateKnowledgeSourcePath(value) {
     if (!value.trim()) {
         return "empty";
     }
+    if (value.toLowerCase().startsWith("ingest://")) {
+        return isIngestReference(value) ? null : "unsafe";
+    }
     if (isExternalReference(value)) {
         return null;
     }
@@ -946,6 +1172,13 @@ function validateKnowledgeSourcePath(value) {
 function isKnowledgeSourceFile(projectRoot, sourcePath) {
     return isRegularFileWithoutSymlink(path.join(projectRoot, sourcePath));
 }
+function isResolvedKnowledgeSource(projectRoot, sourcePath) {
+    if (isIngestReference(sourcePath)) {
+        const parsed = parseIngestReference(sourcePath);
+        return parsed !== null && isRegularFileWithoutSymlink(harnessPath(projectRoot, "ingest", parsed.kind, `${parsed.id}.json`));
+    }
+    return isKnowledgeSourceFile(projectRoot, sourcePath);
+}
 function mergeList(existing, next) {
     if (next === undefined) {
         return existing;
@@ -1142,11 +1375,29 @@ function extractMarkdownBody(content) {
     return content.slice(endIndex).replace(/^\r?\n---\r?\n?/, "").trim();
 }
 function isExternalReference(value) {
+    if (value.toLowerCase().startsWith("ingest://")) {
+        return false;
+    }
     if (/^[A-Za-z]:/.test(value)) {
         return false;
     }
     return /^[a-z][a-z0-9+.-]*:/i.test(value);
 }
+function isIngestReference(value) {
+    return /^ingest:\/\/(?:prd|openapi|ui-package)\/[a-z0-9][a-z0-9._-]{1,80}$/i.test(value)
+        && !value.includes("..")
+        && !/[?#]/.test(value);
+}
+function parseIngestReference(value) {
+    const match = /^ingest:\/\/(prd|openapi|ui-package)\/([a-z0-9][a-z0-9._-]{1,80})$/i.exec(value);
+    if (!match?.[1] || !match[2]) {
+        return null;
+    }
+    return {
+        kind: match[1].toLowerCase(),
+        id: match[2]
+    };
+}
 function isBroadCoverageItem(value) {
     const normalized = value.trim().toLowerCase();
     if (!normalized) {
@@ -1167,6 +1418,35 @@ function hasCoverageBodyDrift(projectRoot, card) {
     const content = safeRead(path.join(projectRoot, card.path));
     return content !== null && /\bCoverage:\s*Not specified\./i.test(extractMarkdownBody(content));
 }
+function isDraftPlaceholderCoverage(value) {
+    const normalized = value.trim().toLowerCase();
+    return (normalized.startsWith("<") || normalized.endsWith(">"))
+        && (normalized.includes("precise section")
+            || normalized.includes("acceptance block")
+            || normalized === "<precise"
+            || normalized === "or acceptance block>");
+}
+function isDraftPlaceholderVerification(value) {
+    const normalized = value.trim().toLowerCase();
+    return /^<.*>$/.test(normalized)
+        && normalized.includes("specific")
+        && (normalized.includes("check") || normalized.includes("evidence"));
+}
+function ingestLinkedAtomicMetadataErrors(relativePath, metadata) {
+    const errors = [];
+    const requiredLists = [
+        ["scope", metadata.scope],
+        ["tags", metadata.tags],
+        ["coverage", metadata.coverage],
+        ["verification", metadata.verification]
+    ];
+    for (const [field, values] of requiredLists) {
+        if (values.length === 0) {
+            errors.push(`${relativePath} active ingest-linked atomic knowledge must include ${field}.`);
+        }
+    }
+    return errors;
+}
 function summarizePrdSources(projectRoot, cards, requiredSources = []) {
     const grouped = new Map();
     for (const sourcePath of discoverPrdSourceFiles(projectRoot)) {
@@ -1182,16 +1462,30 @@ function summarizePrdSources(projectRoot, cards, requiredSources = []) {
     }
     return [...grouped.entries()]
         .sort(([left], [right]) => left.localeCompare(right))
-        .map(([sourcePath, sourceCards]) => ({
-        path: sourcePath,
-        cardCount: sourceCards.length,
-        activeCardCount: sourceCards.filter((card) => card.status === "active").length,
-        cardIds: sourceCards.map((card) => card.id).sort(),
-        scopes: [...new Set(sourceCards.flatMap((card) => card.scope))].sort(),
-        tags: [...new Set(sourceCards.flatMap((card) => card.tags))].sort(),
-        coverage: [...new Set(sourceCards.flatMap((card) => card.coverage))].sort(),
-        prdAnchors: [...new Set(sourceCards.flatMap((card) => card.prdAnchors))].sort()
-    }));
+        .map(([sourcePath, sourceCards]) => {
+        const cardIds = sourceCards.map((card) => card.id).sort();
+        const scopes = [...new Set(sourceCards.flatMap((card) => card.scope))].sort();
+        const tags = [...new Set(sourceCards.flatMap((card) => card.tags))].sort();
+        const coverage = [...new Set(sourceCards.flatMap((card) => card.coverage))].sort();
+        const prdAnchors = [...new Set(sourceCards.flatMap((card) => card.prdAnchors))].sort();
+        return {
+            path: sourcePath,
+            cardCount: sourceCards.length,
+            activeCardCount: sourceCards.filter((card) => card.status === "active").length,
+            cardIds: selectedIndexDetails(cardIds),
+            scopes: selectedIndexDetails(scopes),
+            tags: selectedIndexDetails(tags),
+            coverage: selectedIndexDetails(coverage),
+            prdAnchors: selectedIndexDetails(prdAnchors),
+            omitted: {
+                cardIds: omittedIndexDetails(cardIds),
+                scopes: omittedIndexDetails(scopes),
+                tags: omittedIndexDetails(tags),
+                coverage: omittedIndexDetails(coverage),
+                prdAnchors: omittedIndexDetails(prdAnchors)
+            }
+        };
+    });
 }
 function summarizeModules(cards) {
     const atomicCards = cards.filter((card) => card.kind && card.status === "active");
@@ -1204,6 +1498,7 @@ function summarizeModules(cards) {
             card.related.includes(moduleCard.id) ||
             card.sourcePaths.some((sourcePath) => moduleSources.has(sourcePath)) ||
             card.scope.some((scope) => moduleCard.scope.includes(scope)));
+        const atomicCardIds = relatedAtomicCards.map((card) => card.id).sort();
         return {
             id: moduleCard.id,
             path: moduleCard.path,
@@ -1214,11 +1509,18 @@ function summarizeModules(cards) {
             tags: moduleCard.tags,
             related: moduleCard.related,
             atomicCardCount: relatedAtomicCards.length,
-            atomicCardIds: relatedAtomicCards.map((card) => card.id).sort()
+            atomicCardIds: selectedIndexDetails(atomicCardIds),
+            omittedAtomicCardIds: omittedIndexDetails(atomicCardIds)
         };
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
+function selectedIndexDetails(values) {
+    return values.slice(0, MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS);
+}
+function omittedIndexDetails(values) {
+    return Math.max(0, values.length - MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS);
+}
 function discoverPrdSourceFiles(projectRoot) {
     const roots = ["docs/prd", "docs/requirements", "prd", "requirements"];
     const rootSources = roots.flatMap((root) => {
@@ -1237,6 +1539,9 @@ function discoverPrdSourceFiles(projectRoot) {
 }
 function isPrdSourcePath(sourcePath) {
     const normalized = sourcePath.replace(/\\/g, "/");
+    if (/^ingest:\/\/prd\//i.test(normalized)) {
+        return isIngestReference(normalized);
+    }
     if (/(^|\/)(prd|requirements?)(\/|[-_.])|(^|\/)docs\/(prd|requirements?)(\/|$)/i.test(normalized)) {
         return true;
     }