@planu/cli 4.14.1 → 5.1.1

package/dist/engine/spec-format/unified-spec-builder.js

@@ -1,6 +1,44 @@
 // engine/spec-format/unified-spec-builder.ts — SPEC-709/SPEC-1010 Bug C: Build unified spec.md.
 // Closes the SPEC-630 residue: every new spec is born unified, never written as a
 // two-file spec.md + technical.md pair only to be merged on the next list_specs run.
+import { stripFrontmatter } from '../frontmatter-parser.js';
+const REQUIRED_SECTIONS = [
+    'Problem',
+    'Goal',
+    'Technical',
+    'Implementation Contract',
+    'Acceptance Criteria',
+    'Files',
+    'Out of scope',
+];
+/** Compose the one canonical persisted spec document from already-grounded inputs. */
+export function buildCanonicalUnifiedSpecContent(input) {
+    const frontmatter = /^---\n[\s\S]*?\n---\n?/.exec(input.leanSpecBody)?.[0]?.trimEnd() ?? '';
+    const source = input.sourceDescription.replace(/\r\n/g, '\n').trim();
+    const explicitProblem = extractTopLevelSectionBody(source, 'Problem');
+    const proseBeforeHeading = source.split(/^##[ \t]+\S.*$/m, 1)[0]?.trim() ?? '';
+    const problem = firstNonEmpty(explicitProblem, proseBeforeHeading, source);
+    const explicitGoal = extractTopLevelSectionBody(source, 'Goal');
+    const goal = firstNonEmpty(explicitGoal, firstSentence(problem), problem);
+    const explicitTechnical = extractTopLevelSectionBody(source, 'Technical');
+    const generatedNotes = extractTopLevelSectionBody(input.technicalBody, 'Implementation Notes');
+    const technical = firstNonEmpty(explicitTechnical, generatedNotes, 'Implement only the grounded ownership and observable behavior declared by this contract.');
+    const acceptance = extractExecutableCriteria(source, input.criteria);
+    const explicitOutOfScope = extractTopLevelSectionBody(source, 'Out of scope');
+    const outOfScope = input.outOfScope.length > 0
+        ? input.outOfScope.map((item) => `- ${item}`).join('\n')
+        : (explicitOutOfScope ?? '');
+    const sections = [
+        renderSection('Problem', problem),
+        renderSection('Goal', goal),
+        renderSection('Technical', technical),
+        input.implementationContract.trim(),
+        renderSection('Acceptance Criteria', acceptance),
+        renderSection('Files', renderOwnedFiles(input.files)),
+        renderSection('Out of scope', outOfScope),
+    ];
+    return `${frontmatter ? `${frontmatter}\n\n` : ''}${sections.join('\n\n')}\n`;
+}
 /**
  * Combine a generated lean spec.md body and a generated lean technical.md body
  * into a single unified spec.md content. The technical body's YAML frontmatter
@@ -78,4 +116,168 @@ function extractSection(body, sectionName) {
     const end = next ? next.index : body.length;
     return body.slice(start, end).trimEnd();
 }
+/** Pure pre-persistence validation for the complete unified spec candidate. */
+// eslint-disable-next-line max-lines-per-function -- validation order mirrors the public issue contract
+export function validateUnifiedSpecCandidate(candidate, options = {}) {
+    const body = stripFrontmatter(candidate.replace(/\r\n/g, '\n'));
+    const scannable = maskFencedAndQuotedText(body);
+    const issues = [];
+    const positions = new Map();
+    for (const section of REQUIRED_SECTIONS) {
+        const pattern = new RegExp(`^##[ \\t]+${escapeRegex(section)}[ \\t]*$`, 'gim');
+        positions.set(section, Array.from(scannable.matchAll(pattern), (match) => match.index));
+    }
+    for (const section of REQUIRED_SECTIONS) {
+        const matches = positions.get(section) ?? [];
+        if (matches.length === 0) {
+            issues.push({
+                code: 'MISSING_REQUIRED_SECTION',
+                section,
+                message: `Missing required top-level section: ${section}`,
+            });
+        }
+        else if (matches.length > 1) {
+            issues.push({
+                code: 'DUPLICATE_REQUIRED_SECTION',
+                section,
+                message: `Required top-level section appears more than once: ${section}`,
+            });
+        }
+    }
+    const observedOrder = REQUIRED_SECTIONS.flatMap((section) => (positions.get(section) ?? []).slice(0, 1).map((position) => ({ section, position }))).sort((left, right) => left.position - right.position);
+    if (observedOrder.length === REQUIRED_SECTIONS.length &&
+        observedOrder.some((entry, index) => entry.section !== REQUIRED_SECTIONS[index])) {
+        issues.push({
+            code: 'MISORDERED_REQUIRED_SECTION',
+            message: `Required sections must appear in canonical order: ${REQUIRED_SECTIONS.join(' -> ')}`,
+        });
+    }
+    const embedded = findEmbeddedRequiredSections(body);
+    for (const section of embedded) {
+        issues.push({
+            code: 'EMBEDDED_REQUIRED_SECTION',
+            section,
+            message: `Required section heading is embedded in quoted, fenced, or nested content: ${section}`,
+        });
+    }
+    if (/\b(?:Needs decision|TBD|TODO)\b/i.test(scannable)) {
+        issues.push({
+            code: 'UNRESOLVED_CONTRACT_PLACEHOLDER',
+            message: 'Unified candidate contains an unresolved contract placeholder.',
+        });
+    }
+    const acceptanceSection = extractTopLevelSectionBody(scannable, 'Acceptance Criteria');
+    if (acceptanceSection === null ||
+        !/\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i.test(acceptanceSection)) {
+        issues.push({
+            code: 'MISSING_EXECUTABLE_CRITERIA',
+            section: 'Acceptance Criteria',
+            message: 'Acceptance Criteria must contain executable GIVEN/WHEN/THEN behavior.',
+        });
+    }
+    if (options.groundedFilePaths !== undefined) {
+        const grounded = new Set(options.groundedFilePaths);
+        const filesSection = extractTopLevelSectionBody(scannable, 'Files') ?? '';
+        const ownedPaths = Array.from(filesSection.matchAll(/^[ \t]*-[ \t]+`?([^`\r\n]+?)`?[ \t]*$/gm), (match) => match[1]?.trim() ?? '').filter((path) => path.length > 0 && path !== 'None.');
+        for (const path of [...new Set(ownedPaths)]) {
+            if (!grounded.has(path)) {
+                issues.push({
+                    code: 'UNGROUNDED_FILE_OWNERSHIP',
+                    path,
+                    message: `File ownership is not grounded in explicit input or project evidence: ${path}`,
+                });
+            }
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}
+function maskFencedAndQuotedText(body) {
+    const lines = body.split('\n');
+    let fence = null;
+    return lines
+        .map((line) => {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (marker) {
+            const kind = marker[0];
+            fence = fence === null ? kind : fence === kind ? null : fence;
+            return ' '.repeat(line.length);
+        }
+        if (fence !== null || /^\s*>/.test(line)) {
+            return ' '.repeat(line.length);
+        }
+        return line;
+    })
+        .join('\n');
+}
+function findEmbeddedRequiredSections(body) {
+    const embedded = new Set();
+    let fence = null;
+    for (const line of body.split('\n')) {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (marker) {
+            const kind = marker[0];
+            fence = fence === null ? kind : fence === kind ? null : fence;
+            continue;
+        }
+        const candidate = (fence !== null ? line : line.replace(/^\s*>\s?/, '')).trim();
+        if (fence === null && !/^\s*>/.test(line) && !/^#{3,6}\s+/.test(line)) {
+            continue;
+        }
+        const title = /^#{2,6}\s+(.+?)\s*$/.exec(candidate)?.[1];
+        const canonical = REQUIRED_SECTIONS.find((section) => title?.toLowerCase() === section.toLowerCase());
+        if (canonical) {
+            embedded.add(canonical);
+        }
+    }
+    return [...embedded];
+}
+function extractTopLevelSectionBody(body, section) {
+    const heading = new RegExp(`^##[ \\t]+${escapeRegex(section)}[ \\t]*$`, 'mi').exec(body);
+    if (!heading) {
+        return null;
+    }
+    const start = heading.index + heading[0].length;
+    const rest = body.slice(start);
+    const next = /^##[ \t]+\S.*$/m.exec(rest);
+    return rest.slice(0, next?.index ?? rest.length).trim();
+}
+function renderSection(title, body) {
+    return `## ${title}\n\n${body.trim()}`;
+}
+function firstNonEmpty(...values) {
+    return (values.find((value) => value !== undefined && value !== null && value.length > 0) ?? '');
+}
+function firstSentence(text) {
+    const sentence = text
+        .split(/(?<=[.!?])\s+/)
+        .map((part) => part.trim())
+        .find((part) => part.length > 0 && !part.startsWith('#'));
+    return sentence ?? null;
+}
+function extractExecutableCriteria(source, criteria) {
+    const explicit = /\bGIVEN\b[\s\S]*?(?=(?:\n##|\bFILES:|\bFUNCTIONS:|\bTEST:|$))/i
+        .exec(source)?.[0]
+        ?.trim()
+        .replace(/[.\s]+$/, '.');
+    if (explicit) {
+        return `- ${explicit}`;
+    }
+    return criteria
+        .map((criterion) => `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${criterion.text}`)
+        .join('\n');
+}
+function renderOwnedFiles(files) {
+    const sections = [];
+    for (const [title, entries] of [
+        ['Create', files.create],
+        ['Modify', files.modify],
+        ['Test', files.test],
+    ]) {
+        sections.push(`### ${title}`);
+        sections.push('');
+        sections.push(...(entries.length > 0 ? entries.map((entry) => `- \`${entry.path}\``) : ['- None.']));
+        sections.push('');
+    }
+    return sections.join('\n').trim();
+}
 //# sourceMappingURL=unified-spec-builder.js.map

package/dist/engine/spec-migrator/canonical-deduplicator.d.ts

@@ -0,0 +1,18 @@
+import type { CanonicalRepairManifest, CanonicalRepairPlan, CanonicalRepairRawStore, RepairCanonicalStoreInput } from '../../types/index.js';
+declare function digest(value: Buffer | string): string;
+declare function isContained(parent: string, child: string): boolean;
+declare function artifactPath(projectId: string, artifactId: string): string;
+declare function parseRawStore(raw: Buffer): CanonicalRepairRawStore;
+/** Pure planner. It does not read or write the canonical store. */
+export declare function buildCanonicalRepairPlan(raw: Buffer, manifest: CanonicalRepairManifest, manifestDigest?: string, requestedProjectId?: string): CanonicalRepairPlan;
+/** Runs dry-run or the explicitly authorized, lock-protected repair. */
+export declare function repairDuplicateSpecIds(input: RepairCanonicalStoreInput): Promise<CanonicalRepairPlan>;
+export declare function rollbackCanonicalRepair(projectId: string, receiptPath: string): Promise<void>;
+export declare const CANONICAL_DEDUPLICATOR_INTERNALS: {
+    digest: typeof digest;
+    parseRawStore: typeof parseRawStore;
+    artifactPath: typeof artifactPath;
+    isContained: typeof isContained;
+};
+export {};
+//# sourceMappingURL=canonical-deduplicator.d.ts.map