@gobing-ai/knowledge-kit 0.0.13 → 0.0.14

package/plugins/sp/scripts/dogfood-testing/validate-report.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// plugins/sp/scripts/dogfood-testing/validate-report.ts
+import { readFileSync } from 'node:fs';
+
+var REQUIRED_SECTIONS = [1, 2, 3, 4, 5, 6];
+var CANONICAL_PROTOCOL = 'sp:dogfood-testing@1.2';
+function countSectionHeadings(markdown, section) {
+    const re = new RegExp(`^### ${section}\\.`, 'gm');
+    return (markdown.match(re) ?? []).length;
+}
+function countLedgerDataRows(markdown) {
+    const heading = markdown.match(/^### 3\. Monitor Ledger\s*$/m);
+    if (!heading || heading.index === undefined) return null;
+    const after = markdown.slice(heading.index + heading[0].length);
+    const nextHeading = after.search(/^### /m);
+    const body = nextHeading === -1 ? after : after.slice(0, nextHeading);
+    const rows = body
+        .split(`
+`)
+        .filter((line) => line.trim().startsWith('|'))
+        .filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim()))
+        .filter((line) => !/^\|\s*`?drift:/.test(line.trim()));
+    return Math.max(rows.length - 1, 0);
+}
+function declaredExecutedSteps(markdown) {
+    const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/);
+    return match ? Number.parseInt(match[1], 10) : null;
+}
+function validateReport(markdown) {
+    const errors = [];
+    if (!markdown.includes('── Dogfood Summary ──')) errors.push('missing_footer');
+    if (!markdown.includes('[Live:')) errors.push('missing_live_path');
+    if (!markdown.includes('[Report:')) errors.push('missing_report_path');
+    for (const section of REQUIRED_SECTIONS) {
+        const count = countSectionHeadings(markdown, section);
+        if (count === 0) errors.push(`missing_section:${section}`);
+        if (count > 1) errors.push(`duplicate_section:${section}`);
+    }
+    if (!markdown.includes('#### Fixed') || !markdown.includes('#### Unresolved')) {
+        errors.push('missing_issues_subheads');
+    }
+    const protocolMatch = markdown.match(/^protocol:\s*(\S+)\s*$/m);
+    if (!protocolMatch || protocolMatch[1] !== CANONICAL_PROTOCOL) {
+        errors.push('protocol_string');
+    }
+    const executed = declaredExecutedSteps(markdown);
+    if (executed === null) {
+        errors.push('missing_steps_declared');
+    } else {
+        const rows = countLedgerDataRows(markdown);
+        if (rows === null || rows !== executed) {
+            errors.push('ledger_cardinality');
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+function parseValidateCliArgs(argv) {
+    let file = null;
+    let json = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') help = true;
+        else if (a === '--json') json = true;
+        else if (a === '--file') file = argv[++i] ?? null;
+        else if (!a.startsWith('-') && file === null) file = a;
+    }
+    return { file, json, help };
+}
+var VALIDATE_CLI_USAGE = `Usage:
+  bun plugins/sp/scripts/dogfood-testing/validate-report.ts --file <report.md> [--json]
+
+Exit codes:
+  0  report validates clean (complete-report shape)
+  2  validation failed (errors on stdout / --json)
+  1  usage error
+
+Phase 4 finalize MUST run this before status: complete (task 0278 R6).
+On exit 2: set status: aborted and list error codes under #### Unresolved.`;
+function runValidateCli(argv, readFile) {
+    const { file, json, help } = parseValidateCliArgs(argv);
+    if (help) return { exitCode: 0, stdout: '', stderr: VALIDATE_CLI_USAGE };
+    if (file === null || file.length === 0) {
+        return { exitCode: 1, stdout: '', stderr: VALIDATE_CLI_USAGE };
+    }
+    let markdown;
+    try {
+        markdown = readFile(file);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, stdout: '', stderr: `Failed to read ${file}: ${msg}` };
+    }
+    const result = validateReport(markdown);
+    if (json) {
+        return {
+            exitCode: result.ok ? 0 : 2,
+            stdout: `${JSON.stringify(result, null, 2)}
+`,
+            stderr: '',
+        };
+    }
+    if (result.ok) {
+        return {
+            exitCode: 0,
+            stdout: `ok
+`,
+            stderr: '',
+        };
+    }
+    return {
+        exitCode: 2,
+        stdout: `${result.errors.join(`
+`)}
+`,
+        stderr: '',
+    };
+}
+function mainCli(argv = process.argv.slice(2)) {
+    const { exitCode, stdout, stderr } = runValidateCli(argv, (p) => readFileSync(p, 'utf8'));
+    if (stdout) process.stdout.write(stdout);
+    if (stderr)
+        process.stderr.write(`${stderr}
+`);
+    return exitCode;
+}
+process.exit(mainCli());
+
+export { mainCli, parseValidateCliArgs, runValidateCli, VALIDATE_CLI_USAGE, validateReport };

package/plugins/sp/scripts/dogfood-testing/validate-report.ts

@@ -0,0 +1,169 @@
+/**
+ * validate-report — @1.2 dogfood report contract checker (task 0276, W6).
+ *
+ * Pure function over a report markdown string → { ok, errors[] } with stable error
+ * codes, callable from tests and by agents finalizing a run. It validates the
+ * *complete-report* shape: the six unique section headings, Issues subheads, the
+ * mandatory summary footer with both delivery paths, frontmatter protocol string,
+ * and ledger↔declared-steps cardinality. Aborted/partial reports are out of scope —
+ * they legitimately lack the footer and Steps line.
+ *
+ * CLI (task 0278 R6): `bun …/validate-report.ts --file <report.md> [--json]`
+ */
+
+import { readFileSync } from 'node:fs';
+
+export interface ReportValidation {
+    ok: boolean;
+    errors: string[];
+}
+
+const REQUIRED_SECTIONS = [1, 2, 3, 4, 5, 6] as const;
+const CANONICAL_PROTOCOL = 'sp:dogfood-testing@1.2';
+
+function countSectionHeadings(markdown: string, section: number): number {
+    const re = new RegExp(`^### ${section}\\.`, 'gm');
+    return (markdown.match(re) ?? []).length;
+}
+
+function countLedgerDataRows(markdown: string): number | null {
+    const heading = markdown.match(/^### 3\. Monitor Ledger\s*$/m);
+    if (!heading || heading.index === undefined) return null;
+    const after = markdown.slice(heading.index + heading[0].length);
+    const nextHeading = after.search(/^### /m);
+    const body = nextHeading === -1 ? after : after.slice(0, nextHeading);
+    const rows = body
+        .split('\n')
+        .filter((line) => line.trim().startsWith('|'))
+        .filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim()))
+        // drift:external rows are documentary (task 0296) — included in the table but
+        // subtracted from the executed-step count, per the @1.2 cardinality contract;
+        // the prescribed code-span form (`drift:external`) matches too (task 0701 R5b).
+        .filter((line) => !/^\|\s*`?drift:/.test(line.trim()));
+    // Minus the header row; what remains are data rows.
+    return Math.max(rows.length - 1, 0);
+}
+
+function declaredExecutedSteps(markdown: string): number | null {
+    const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/);
+    return match ? Number.parseInt(match[1], 10) : null;
+}
+
+export function validateReport(markdown: string): ReportValidation {
+    const errors: string[] = [];
+
+    // Footer (W2/D1) — the mirrored footer block at the report end.
+    if (!markdown.includes('── Dogfood Summary ──')) errors.push('missing_footer');
+    if (!markdown.includes('[Live:')) errors.push('missing_live_path');
+    if (!markdown.includes('[Report:')) errors.push('missing_report_path');
+
+    // Six unique section headings (W2/D3).
+    for (const section of REQUIRED_SECTIONS) {
+        const count = countSectionHeadings(markdown, section);
+        if (count === 0) errors.push(`missing_section:${section}`);
+        if (count > 1) errors.push(`duplicate_section:${section}`);
+    }
+
+    // Issues subheads (W2/D3).
+    if (!markdown.includes('#### Fixed') || !markdown.includes('#### Unresolved')) {
+        errors.push('missing_issues_subheads');
+    }
+
+    // Protocol string (W1/D5) — colon form, exact version.
+    const protocolMatch = markdown.match(/^protocol:\s*(\S+)\s*$/m);
+    if (!protocolMatch || protocolMatch[1] !== CANONICAL_PROTOCOL) {
+        errors.push('protocol_string');
+    }
+
+    // Ledger cardinality (W3/D4) — data rows == declared executed steps.
+    const executed = declaredExecutedSteps(markdown);
+    if (executed === null) {
+        errors.push('missing_steps_declared');
+    } else {
+        const rows = countLedgerDataRows(markdown);
+        if (rows === null || rows !== executed) {
+            errors.push('ledger_cardinality');
+        }
+    }
+
+    return { ok: errors.length === 0, errors };
+}
+
+// ── CLI entry (Phase 4 self-validate — task 0278 R6) ─────────────────────────
+
+export interface ValidateCliArgs {
+    file: string | null;
+    json: boolean;
+    help: boolean;
+}
+
+export function parseValidateCliArgs(argv: string[]): ValidateCliArgs {
+    let file: string | null = null;
+    let json = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') help = true;
+        else if (a === '--json') json = true;
+        else if (a === '--file') file = argv[++i] ?? null;
+        else if (!a.startsWith('-') && file === null) file = a;
+    }
+    return { file, json, help };
+}
+
+export const VALIDATE_CLI_USAGE = `Usage:
+  bun plugins/sp/scripts/dogfood-testing/validate-report.ts --file <report.md> [--json]
+
+Exit codes:
+  0  report validates clean (complete-report shape)
+  2  validation failed (errors on stdout / --json)
+  1  usage error
+
+Phase 4 finalize MUST run this before status: complete (task 0278 R6).
+On exit 2: set status: aborted and list error codes under #### Unresolved.`;
+
+export function runValidateCli(
+    argv: string[],
+    readFile: (path: string) => string,
+): { exitCode: number; stdout: string; stderr: string } {
+    const { file, json, help } = parseValidateCliArgs(argv);
+    if (help) return { exitCode: 0, stdout: '', stderr: VALIDATE_CLI_USAGE };
+    if (file === null || file.length === 0) {
+        return { exitCode: 1, stdout: '', stderr: VALIDATE_CLI_USAGE };
+    }
+    let markdown: string;
+    try {
+        markdown = readFile(file);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, stdout: '', stderr: `Failed to read ${file}: ${msg}` };
+    }
+    const result = validateReport(markdown);
+    if (json) {
+        return {
+            exitCode: result.ok ? 0 : 2,
+            stdout: `${JSON.stringify(result, null, 2)}\n`,
+            stderr: '',
+        };
+    }
+    if (result.ok) {
+        return { exitCode: 0, stdout: 'ok\n', stderr: '' };
+    }
+    return {
+        exitCode: 2,
+        stdout: `${result.errors.join('\n')}\n`,
+        stderr: '',
+    };
+}
+
+/** CLI entry for Phase 4 self-validate (import.meta.main). */
+export function mainCli(argv: string[] = process.argv.slice(2)): number {
+    const { exitCode, stdout, stderr } = runValidateCli(argv, (p) => readFileSync(p, 'utf8'));
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(`${stderr}\n`);
+    return exitCode;
+}
+
+if (import.meta.main) {
+    process.exit(mainCli());
+}

package/plugins/sp/scripts/feature-dev-precheck.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/feature-dev-precheck.ts
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+var BLOCKING_STATUSES = ['backlog', 'wip', 'testing', 'blocked'];
+var KNOWN_STATUSES = ['todo', 'done', 'cancelled', ...BLOCKING_STATUSES];
+function identityRc(featureId, runId) {
+    return featureId && runId ? 0 : 1;
+}
+function featureIdentityMatches(raw, featureId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return false;
+    }
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) && parsed.id === featureId;
+}
+function rosterIsNonEmptyArray(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return false;
+    }
+    return Array.isArray(parsed) && parsed.length > 0;
+}
+function rosterContractHolds(rows) {
+    const seen = new Set();
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object') return false;
+        if (typeof row.wbs !== 'string' || row.wbs.length === 0) return false;
+        if (seen.has(row.wbs)) return false;
+        seen.add(row.wbs);
+        if (typeof row.status !== 'string' || !KNOWN_STATUSES.includes(row.status)) {
+            return false;
+        }
+    }
+    return true;
+}
+function hasBlockingStatus(rows) {
+    return rows.some((row) => typeof row.status === 'string' && BLOCKING_STATUSES.includes(row.status));
+}
+function freezeTodoList(rows) {
+    return rows
+        .filter((row) => row.status === 'todo' && typeof row.wbs === 'string')
+        .map((row) => row.wbs)
+        .sort()
+        .join(',');
+}
+function spurCommand(spurBin) {
+    const parts = (spurBin ?? 'spur')
+        .trim()
+        .split(/\s+/)
+        .filter((p) => p.length > 0);
+    return { cmd: parts[0] ?? 'spur', prefix: parts.slice(1) };
+}
+function readFileSyncRaw(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    } catch {
+        return '';
+    }
+}
+function runFeatureDevPrecheck(env, options = {}) {
+    const cwd = options.cwd;
+    const runDir = join('.spur', 'run');
+    mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+    const abs = (p) => (cwd ? join(cwd, p) : p);
+    const featureFile = join(runDir, `${env.__runId ?? ''}-feature-dev-feature.json`);
+    const rosterFile = join(runDir, `${env.__runId ?? ''}-feature-dev-roster.json`);
+    const tasksFile = join(runDir, `${env.__runId ?? ''}-feature-dev-tasks.txt`);
+    const statusFile = join(runDir, `${env.__runId ?? ''}-feature-dev-precheck.status`);
+    const featureId = env.featureId ?? '';
+    rmSync(abs(statusFile), { force: true });
+    const { cmd, prefix } = spurCommand(env.spurBin);
+    const read = (args, target) => {
+        const result = spawnSync(cmd, [...prefix, ...args], {
+            cwd,
+            encoding: 'utf8',
+            ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+        });
+        if (result.error !== undefined) {
+            writeFileSync(
+                abs(target),
+                `spawn failed: ${result.error.message}
+`,
+            );
+            return 127;
+        }
+        writeFileSync(abs(target), `${result.stdout ?? ''}${result.stderr ?? ''}`);
+        return result.status ?? 1;
+    };
+    const idRc = identityRc(featureId, env.__runId);
+    const showRc = idRc === 0 ? read(['feature', 'show', featureId, '--json'], featureFile) : 1;
+    const listRc =
+        idRc === 0 && showRc === 0 && featureIdentityMatches(readFileSyncRaw(abs(featureFile)), featureId)
+            ? read(['task', 'list', '--feature', featureId, '--json'], rosterFile)
+            : 1;
+    const fail = (message) => {
+        process.stderr.write(`${message}
+`);
+        writeFileSync(
+            abs(statusFile),
+            `FAIL
+`,
+        );
+        return { status: 'FAIL', featureFile, rosterFile, tasksFile, statusFile, tasks: '' };
+    };
+    if (idRc !== 0 || showRc !== 0 || listRc !== 0) {
+        return fail(
+            `feature-dev precheck: missing featureId/runId, unknown feature '${featureId}', or unreadable roster (rc ${idRc}/${showRc}/${listRc}) \u2014 supply an existing planned feature via /sp:dev-plan or /sp:dev-idea; nothing was auto-created or re-planned`,
+        );
+    }
+    const rosterRaw = readFileSyncRaw(abs(rosterFile));
+    if (!rosterIsNonEmptyArray(rosterRaw)) {
+        return fail(
+            `feature-dev precheck: roster at ${rosterFile} is malformed, not an array, or empty \u2014 plan the feature first via /sp:dev-plan; refusing to replan or run an empty batch`,
+        );
+    }
+    const rows = JSON.parse(rosterRaw);
+    if (!rosterContractHolds(rows)) {
+        return fail(
+            `feature-dev precheck: roster has empty/duplicate/mismatched WBS identities or unknown statuses at ${rosterFile} \u2014 repair the task corpus; refusing to batch a broken roster`,
+        );
+    }
+    if (hasBlockingStatus(rows)) {
+        return fail(
+            'feature-dev precheck: linked task(s) are backlog/wip/testing/blocked \u2014 refine or resume them through their own task pipelines before batching; refusing to launch overlapping work',
+        );
+    }
+    const tasks = freezeTodoList(rows);
+    writeFileSync(abs(tasksFile), tasks);
+    writeFileSync(
+        abs(statusFile),
+        `PASS
+`,
+    );
+    return { status: 'PASS', featureFile, rosterFile, tasksFile, statusFile, tasks };
+}
+var FEATURE_DEV_PRECHECK_USAGE =
+    'usage: feature-dev-precheck.ts  (env: featureId, __runId, optional spurBin) \u2014 no subcommands';
+function main(argv, env = process.env) {
+    if (argv.length > 0) {
+        process.stderr.write(`${FEATURE_DEV_PRECHECK_USAGE}
+`);
+        return 2;
+    }
+    runFeatureDevPrecheck(env);
+    return 0;
+}
+process.exit(main(process.argv.slice(2)));
+
+export {
+    BLOCKING_STATUSES,
+    FEATURE_DEV_PRECHECK_USAGE,
+    featureIdentityMatches,
+    freezeTodoList,
+    hasBlockingStatus,
+    identityRc,
+    KNOWN_STATUSES,
+    main,
+    rosterContractHolds,
+    rosterIsNonEmptyArray,
+    runFeatureDevPrecheck,
+    spurCommand,
+};