frontend-harness 0.8.0 → 0.8.2

package/dist/runtime/knowledge/core.js

@@ -8,6 +8,8 @@ import { kindTypeMap, knowledgeKinds, knowledgeStabilities, knowledgeStatuses, k
 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_OUTLINE_HEADINGS = 80;
+export const MAX_KNOWLEDGE_DRAFT_EXTRACTION_ITEMS = 40;
 export const MAX_KNOWLEDGE_INDEX_CARDS = 20;
 export const MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS = 20;
 const MAX_KNOWLEDGE_REFERENCE_SUGGESTIONS = 20;
@@ -37,6 +39,9 @@ export function promoteKnowledge(projectRoot, input) {
         createdAt,
         scope: splitList(input.scope),
         tags: splitList(input.tags),
+        verification: splitList(input.verification),
+        coverage: splitList(input.coverage),
+        prdAnchors: splitList(input.anchor),
         sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge promote --source")
     });
     writeText(path.join(projectRoot, relativePath), content);
@@ -159,6 +164,24 @@ export function addKnowledge(projectRoot, input) {
         createdAt
     };
 }
+export function outlineKnowledgeFromIngest(projectRoot, input) {
+    if (!input.ref?.trim()) {
+        throw new Error("knowledge outline requires --ref ingest://<kind>/<source-id>");
+    }
+    const record = showIngestRecord(projectRoot, input.ref);
+    const outlineSelection = buildKnowledgeOutline(projectRoot, record);
+    return {
+        contractVersion: 1,
+        ingestRef: record.ingestRef,
+        ingestKind: record.kind,
+        source: record.source.value,
+        sourceType: record.source.type,
+        outline: outlineSelection.headings,
+        limits: {
+            headings: outlineSelection.limits
+        }
+    };
+}
 export function draftKnowledgeFromIngest(projectRoot, input) {
     if (!input.ref?.trim()) {
         throw new Error("knowledge draft requires --ref ingest://<kind>/<source-id>");
@@ -182,6 +205,10 @@ export function draftKnowledgeFromIngest(projectRoot, input) {
     const contentFlag = contentFlagForKind(recommendedKind);
     const updateCandidateSelection = draftUpdateCandidates(projectRoot, record, defaults);
     const updateCandidates = updateCandidateSelection.candidates;
+    const outlineSelection = buildKnowledgeOutline(projectRoot, record);
+    const extractionItemSelection = draftExtractionItems(record, outlineSelection.headings, updateCandidates);
+    const outlineLimits = outlineSelection.limits.total > 0 ? outlineSelection.limits : undefined;
+    const extractionLimits = extractionItemSelection.limits.total > 0 ? extractionItemSelection.limits : undefined;
     const args = [
         "knowledge",
         "add",
@@ -219,13 +246,20 @@ export function draftKnowledgeFromIngest(projectRoot, input) {
         command: "frontend-harness knowledge add --json",
         args,
         updateCandidates,
+        ...(outlineSelection.headings.length ? { outline: outlineSelection.headings } : {}),
+        ...(extractionItemSelection.items.length ? { extractionItems: extractionItemSelection.items } : {}),
         limits: {
-            updateCandidates: updateCandidateSelection.limits
+            updateCandidates: updateCandidateSelection.limits,
+            ...(outlineLimits ? { outlineHeadings: outlineLimits } : {}),
+            ...(extractionLimits ? { extractionItems: extractionLimits } : {})
         },
         requiredEdits: [
             ...(updateCandidateSelection.limits.total > 0
                 ? ["Prefer a matching update candidate before adding a new card for the same source."]
                 : []),
+            ...(extractionItemSelection.items.length
+                ? ["Use extractionItems as the source checklist; add, update, or explicitly skip each required source block."]
+                : []),
             `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.",
@@ -278,6 +312,228 @@ function draftUpdateCandidates(projectRoot, record, defaults) {
         }
     };
 }
+function buildKnowledgeOutline(projectRoot, record) {
+    if (record.kind !== "prd" || record.source.type !== "project-file" || !/\.md$/i.test(record.source.value)) {
+        return {
+            headings: [],
+            limits: { selected: 0, total: 0, omitted: 0 }
+        };
+    }
+    const fullPath = path.join(projectRoot, record.source.value);
+    const content = safeRead(fullPath);
+    if (content === null) {
+        return {
+            headings: [],
+            limits: { selected: 0, total: 0, omitted: 0 }
+        };
+    }
+    const headings = parseKnowledgeOutlineHeadings(content);
+    const selected = headings.slice(0, MAX_KNOWLEDGE_OUTLINE_HEADINGS);
+    return {
+        headings: selected,
+        limits: {
+            selected: selected.length,
+            total: headings.length,
+            omitted: Math.max(0, headings.length - selected.length)
+        }
+    };
+}
+function parseKnowledgeOutlineHeadings(content) {
+    const lines = content.split(/\r?\n/);
+    const rawHeadings = [];
+    const stack = [];
+    const idCounts = new Map();
+    lines.forEach((line, index) => {
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (!match?.[1] || !match[2]) {
+            return;
+        }
+        const level = match[1].length;
+        const title = match[2].replace(/\s+#+$/, "").trim();
+        if (!title) {
+            return;
+        }
+        while (stack.length && stack[stack.length - 1].level >= level) {
+            stack.pop();
+        }
+        const baseId = slugify(title) || `heading-${index + 1}`;
+        const count = idCounts.get(baseId) ?? 0;
+        idCounts.set(baseId, count + 1);
+        const id = count === 0 ? baseId : `${baseId}-${count + 1}`;
+        const parent = stack[stack.length - 1] ?? null;
+        const headingPath = [...(parent?.path ?? []), title];
+        rawHeadings.push({
+            id,
+            title,
+            level,
+            lineStart: index + 1,
+            parentId: parent?.id ?? null,
+            path: headingPath
+        });
+        stack.push({ id, level, title, path: headingPath });
+    });
+    return rawHeadings.map((heading, index) => {
+        const nextHeading = rawHeadings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+        const classification = classifyOutlineHeading(heading.title, heading.path);
+        return {
+            ...heading,
+            lineEnd: nextHeading ? nextHeading.lineStart - 1 : lines.length,
+            extractionRequired: classification.extractionRequired,
+            suggestedKind: classification.suggestedKind,
+            reason: classification.reason,
+            coverage: heading.path.join(" > ")
+        };
+    });
+}
+function classifyOutlineHeading(title, headingPath) {
+    const text = normalize([...headingPath, title].join(" "));
+    if (/(?:不做|不扩展|边界|风险|异常|歧义|pitfall|risk|out of scope|non goal|not doing)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "pitfall",
+            reason: "source block describes boundary, exception, risk, ambiguity, or non-goal information"
+        };
+    }
+    if (/(?:权限|按钮|操作|可见|允许|禁止|permission|button|action|visibility)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "permission",
+            reason: "source block describes action availability, visibility, or permission behavior"
+        };
+    }
+    if (/(?:流程|链路|流转|workflow|process|journey|flow|lifecycle|状态机)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "workflow",
+            reason: "source block describes workflow, lifecycle, or state transition semantics"
+        };
+    }
+    if (/(?:字段|枚举|状态|术语|定义|field|enum|status|term|definition)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "term",
+            reason: "source block defines fields, states, terms, or enumerations"
+        };
+    }
+    if (/(?:模块|页面结构|区域|信息层级|布局|module|section|layout|region)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "module_summary",
+            reason: "source block describes module, page region, layout, or structure boundaries"
+        };
+    }
+    if (/(?:规则|校验|验收|条件|策略|计算|rule|validation|acceptance|criteria|condition|policy)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "rule",
+            reason: "source block describes durable rule, validation, acceptance, condition, or policy"
+        };
+    }
+    return {
+        extractionRequired: false,
+        suggestedKind: "none",
+        reason: "source block appears descriptive; mark skip if it has no durable implementation knowledge"
+    };
+}
+function draftExtractionItems(record, headings, sourceUpdateCandidates) {
+    const requiredHeadings = headings.filter((heading) => heading.extractionRequired && heading.suggestedKind !== "none");
+    const items = requiredHeadings
+        .slice(0, MAX_KNOWLEDGE_DRAFT_EXTRACTION_ITEMS)
+        .map((heading) => draftExtractionItem(record, heading, sourceUpdateCandidates));
+    return {
+        items,
+        limits: {
+            selected: items.length,
+            total: requiredHeadings.length,
+            omitted: Math.max(0, requiredHeadings.length - items.length)
+        }
+    };
+}
+function draftExtractionItem(record, heading, sourceUpdateCandidates) {
+    if (heading.suggestedKind === "none") {
+        throw new Error(`cannot draft extraction item for non-required heading: ${heading.id}`);
+    }
+    const suggestedKind = heading.suggestedKind === "module_summary" ? "module_summary" : heading.suggestedKind;
+    const subject = titleCase(heading.title.replace(/^\d+(?:\.\d+)*\s*/, ""));
+    const scope = draftScope(record);
+    const tags = suggestedKind === "module_summary" ? `prd,module,${scope}` : `prd,${suggestedKind},${scope}`;
+    const itemId = slugify(`${record.id}-${heading.title}`) || `${record.id}-${heading.id}`;
+    const updateCandidates = sourceUpdateCandidates.filter((candidate) => candidate.title.includes(heading.title) || candidate.summary.includes(heading.title) || candidate.id.includes(slugify(heading.title)));
+    if (suggestedKind === "module_summary") {
+        return {
+            id: itemId,
+            headingId: heading.id,
+            title: heading.title,
+            coverage: heading.coverage,
+            suggestedKind,
+            extractionRequired: true,
+            reason: heading.reason,
+            command: "frontend-harness knowledge module --json",
+            args: [
+                "knowledge",
+                "module",
+                "--json",
+                "--id",
+                itemId,
+                "--title",
+                subject,
+                "--summary",
+                `<module summary distilled from ${heading.coverage}>`,
+                "--body",
+                `<structured module facts from ${heading.coverage}>`,
+                "--source",
+                record.ingestRef,
+                "--coverage",
+                heading.coverage,
+                "--verification",
+                "<specific check or evidence required>",
+                "--scope",
+                scope,
+                "--tags",
+                tags
+            ],
+            updateCandidates
+        };
+    }
+    const kind = suggestedKind;
+    const contentFlag = contentFlagForKind(kind);
+    return {
+        id: itemId,
+        headingId: heading.id,
+        title: heading.title,
+        coverage: heading.coverage,
+        suggestedKind: kind,
+        extractionRequired: true,
+        reason: heading.reason,
+        command: "frontend-harness knowledge add --json",
+        args: [
+            "knowledge",
+            "add",
+            "--json",
+            "--id",
+            itemId,
+            "--kind",
+            kind,
+            "--subject",
+            subject,
+            "--summary",
+            `<summary distilled from ${heading.coverage}>`,
+            `--${contentFlag}`,
+            `<atomic ${contentFlag} distilled from ${heading.coverage}>`,
+            "--source",
+            record.ingestRef,
+            "--coverage",
+            heading.coverage,
+            "--verification",
+            "<specific check or evidence required>",
+            "--scope",
+            scope,
+            "--tags",
+            tags
+        ],
+        updateCandidates
+    };
+}
 function recommendedKnowledgeKind(kind) {
     if (kind === "openapi") {
         return "workflow";
@@ -635,6 +891,9 @@ export function checkKnowledge(projectRoot) {
         if ((parsed.metadata.summary?.length ?? 0) > 180) {
             warnings.push(`${relativePath} summary should stay concise for context display.`);
         }
+        if (parsed.metadata.status === "active" && parsed.metadata.type === "prd_semantics") {
+            errors.push(...prdSemanticMetadataErrors(relativePath, parsed.metadata));
+        }
         if (parsed.metadata.kind) {
             const contentValue = primaryAtomicValue(parsed.metadata);
             if (contentValue && normalize(contentValue) === normalize(parsed.metadata.summary ?? "")) {
@@ -1026,6 +1285,7 @@ function renderAtomicBody(kind, subject, summary, contentFields, coverage, prdAn
 }
 function renderKnowledge(input) {
     const summary = firstBodyLine(input.body) ?? input.title;
+    const body = renderBodyWithTraceability(input.body, input.coverage, input.prdAnchors, input.verification);
     return `---
 id: ${yamlScalar(input.id)}
 type: ${yamlScalar(input.type)}
@@ -1035,6 +1295,12 @@ scope:
 ${renderList(input.scope)}
 tags:
 ${renderList(input.tags)}
+verification:
+${renderList(input.verification)}
+coverage:
+${renderList(input.coverage)}
+prd_anchors:
+${renderList(input.prdAnchors)}
 status: ${yamlScalar(input.status)}
 stability: ${yamlScalar(input.stability)}
 updated_at: ${yamlScalar(input.createdAt)}
@@ -1045,7 +1311,7 @@ related: []
 
 # ${input.title}
 
-${input.body}
+${body}
 `;
 }
 function renderList(items) {
@@ -1550,6 +1816,25 @@ function isPrdSourcePath(sourcePath) {
 function isPrdTraceableCard(card) {
     return card.type === "prd_semantics" || card.type === "module_summary" || card.type === "pitfall" || card.type === "glossary";
 }
+function prdSemanticMetadataErrors(relativePath, metadata) {
+    const errors = [];
+    if (metadata.sourcePaths.length === 0) {
+        errors.push(`${relativePath} active PRD semantics must include source_paths.`);
+    }
+    if (metadata.coverage.length === 0) {
+        errors.push(`${relativePath} active PRD semantics must include coverage.`);
+    }
+    if (metadata.scope.length === 0) {
+        errors.push(`${relativePath} active PRD semantics must include scope.`);
+    }
+    if (metadata.tags.length === 0) {
+        errors.push(`${relativePath} active PRD semantics must include tags.`);
+    }
+    if (metadata.verification.length === 0) {
+        errors.push(`${relativePath} active PRD semantics must include verification.`);
+    }
+    return errors;
+}
 function countByType(cards) {
     const counts = Object.fromEntries([...knowledgeTypes].map((type) => [type, 0]));
     for (const card of cards) {