thachvd-kit 1.0.37 → 1.0.39

package/bin/spec-state.js

@@ -0,0 +1,415 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const META_DIR = '_meta';
+const VERIFICATION_FILE = 'verification.json';
+const REVIEW_FILE = 'review.md';
+const PROGRESS_FILE = 'reverse-progress.json';
+const VERIFICATION_SCHEMA_VERSION = 1;
+const PROGRESS_SCHEMA_VERSION = 1;
+
+function portable(value) {
+    return value.split(path.sep).join('/');
+}
+
+function nowIso() {
+    return new Date().toISOString();
+}
+
+function metaRoot(workspaceRoot, manifest) {
+    return path.join(workspaceRoot, manifest.spec_root, META_DIR);
+}
+
+function verificationPath(workspaceRoot, manifest) {
+    return path.join(metaRoot(workspaceRoot, manifest), VERIFICATION_FILE);
+}
+
+function reviewPath(workspaceRoot, manifest) {
+    return path.join(metaRoot(workspaceRoot, manifest), REVIEW_FILE);
+}
+
+function progressSlug(capability) {
+    if (!capability) return null;
+    const slug = String(capability).trim().toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) throw new Error('Capability name must contain letters or numbers');
+    return slug;
+}
+
+function progressFileName(capability = null) {
+    const slug = progressSlug(capability);
+    return slug ? `reverse-progress-${slug}.json` : PROGRESS_FILE;
+}
+
+function progressPath(workspaceRoot, manifest, capability = null) {
+    return path.join(metaRoot(workspaceRoot, manifest), progressFileName(capability));
+}
+
+function ensureMetaRoot(workspaceRoot, manifest) {
+    const directory = metaRoot(workspaceRoot, manifest);
+    fs.mkdirSync(directory, { recursive: true });
+    return directory;
+}
+
+function runGit(repoRoot, args, options = {}) {
+    const spawn = options.spawn || spawnSync;
+    const result = spawn('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8'
+    });
+    if (result.status !== 0) {
+        const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+        return { ok: false, error: stderr || `git ${args.join(' ')} failed`, status: result.status };
+    }
+    return { ok: true, stdout: typeof result.stdout === 'string' ? result.stdout.trim() : '' };
+}
+
+function getRepoHead(repoRoot, options = {}) {
+    const result = runGit(repoRoot, ['rev-parse', 'HEAD'], options);
+    if (!result.ok) return result;
+    return { ok: true, commit: result.stdout };
+}
+
+function captureRepoHeads(workspaceRoot, manifest, options = {}) {
+    const heads = {};
+    for (const repo of manifest.repos) {
+        const repoRoot = path.resolve(workspaceRoot, repo.path);
+        if (!fs.existsSync(repoRoot)) {
+            heads[repo.name] = { ok: false, path: repo.path, error: 'repository path is missing' };
+            continue;
+        }
+        const head = getRepoHead(repoRoot, options);
+        heads[repo.name] = head.ok
+            ? { ok: true, path: repo.path, commit: head.commit }
+            : { ok: false, path: repo.path, error: head.error };
+    }
+    return heads;
+}
+
+function readJsonFile(filePath, label) {
+    if (!fs.existsSync(filePath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        throw new Error(`Cannot parse ${label}: ${error.message}`);
+    }
+}
+
+function readVerification(workspaceRoot, manifest) {
+    const filePath = verificationPath(workspaceRoot, manifest);
+    const data = readJsonFile(filePath, `${manifest.spec_root}/${META_DIR}/${VERIFICATION_FILE}`);
+    if (!data) return null;
+    if (data.schema_version !== VERIFICATION_SCHEMA_VERSION) {
+        throw new Error(`Unsupported verification schema_version: ${data.schema_version}`);
+    }
+    if (data.system && data.system !== manifest.name) {
+        throw new Error(`verification system mismatch: expected ${manifest.name}, got ${data.system}`);
+    }
+    if (!data.repositories || typeof data.repositories !== 'object') {
+        throw new Error('verification.json requires repositories');
+    }
+    if (!data.capabilities || typeof data.capabilities !== 'object') {
+        throw new Error('verification.json requires capabilities');
+    }
+    return data;
+}
+
+function normalizeSourcePath(value) {
+    if (typeof value !== 'string' || !value.trim()) return null;
+    const raw = value.trim().replace(/\\/g, '/');
+    if (raw.startsWith('/') || /^[A-Za-z]:\//.test(raw)) {
+        throw new Error(`source path must be repository-relative: ${value}`);
+    }
+    const normalized = raw.replace(/^\.\//, '').replace(/\/+/g, '/').replace(/\/$/, '');
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+        throw new Error(`source path must stay inside the repository: ${value}`);
+    }
+    return normalized;
+}
+
+function normalizeSourcePaths(value) {
+    if (!Array.isArray(value)) return [];
+    return [...new Set(value
+        .map(normalizeSourcePath)
+        .filter(Boolean))];
+}
+
+function validateVerification(manifest, data) {
+    if (!data || typeof data !== 'object') throw new Error('verification data must be an object');
+    if (data.schema_version !== VERIFICATION_SCHEMA_VERSION) {
+        throw new Error(`verification schema_version must be ${VERIFICATION_SCHEMA_VERSION}`);
+    }
+    if (data.system && data.system !== manifest.name) {
+        throw new Error(`verification system mismatch: expected ${manifest.name}, got ${data.system}`);
+    }
+    const repoNames = new Set(manifest.repos.map(repo => repo.name));
+    for (const repo of manifest.repos) {
+        if (!data.repositories || !data.repositories[repo.name]) {
+            throw new Error(`verification is missing repository: ${repo.name}`);
+        }
+    }
+    for (const [repoName, repoState] of Object.entries(data.repositories || {})) {
+        if (!repoNames.has(repoName)) throw new Error(`verification references unknown repository: ${repoName}`);
+        if (!repoState || typeof repoState.commit !== 'string' || !/^[0-9a-f]{40}$/i.test(repoState.commit.trim())) {
+            throw new Error(`verification repository ${repoName} requires a full Git commit SHA`);
+        }
+    }
+    const capabilityEntries = Object.entries(data.capabilities || {});
+    if (capabilityEntries.length === 0) throw new Error('verification requires at least one capability');
+    for (const [slug, capability] of capabilityEntries) {
+        if (!capability || typeof capability !== 'object') throw new Error(`invalid capability verification: ${slug}`);
+        if (!['verified', 'needs_review', 'blocked'].includes(capability.status)) {
+            throw new Error(`invalid verification status for ${slug}: ${capability.status}`);
+        }
+        capability.source_paths = capability.source_paths || {};
+        capability.verified_commits = capability.verified_commits || {};
+        for (const [repoName, sourcePaths] of Object.entries(capability.source_paths)) {
+            if (!repoNames.has(repoName)) throw new Error(`capability ${slug} references unknown repository: ${repoName}`);
+            capability.source_paths[repoName] = normalizeSourcePaths(sourcePaths);
+            const commit = capability.verified_commits[repoName];
+            if (capability.status === 'verified' && (!commit || !/^[0-9a-f]{40}$/i.test(commit))) {
+                throw new Error(`verified capability ${slug} requires verified_commits.${repoName}`);
+            }
+        }
+        for (const [repoName, commit] of Object.entries(capability.verified_commits)) {
+            if (!repoNames.has(repoName)) throw new Error(`capability ${slug} verified_commits references unknown repository: ${repoName}`);
+            if (!/^[0-9a-f]{40}$/i.test(String(commit))) {
+                throw new Error(`capability ${slug} has invalid verified commit for ${repoName}`);
+            }
+        }
+
+        if (capability.status === 'verified') {
+            const sourceCount = Object.values(capability.source_paths)
+                .reduce((sum, paths) => sum + paths.length, 0);
+            if (sourceCount === 0) {
+                throw new Error(`verified capability ${slug} requires at least one source path`);
+            }
+            if (!capability.evidence || typeof capability.evidence !== 'object') {
+                throw new Error(`verified capability ${slug} requires evidence counts`);
+            }
+            const requiredCounts = [
+                'implementation_claims_checked',
+                'test_claims_checked',
+                'unsupported_claims',
+                'potential_gaps',
+                'broken_anchors'
+            ];
+            for (const key of requiredCounts) {
+                const value = capability.evidence[key];
+                if (!Number.isInteger(value) || value < 0) {
+                    throw new Error(`verified capability ${slug} requires non-negative integer evidence.${key}`);
+                }
+            }
+            for (const key of ['unsupported_claims', 'potential_gaps', 'broken_anchors']) {
+                if (capability.evidence[key] !== 0) {
+                    throw new Error(`verified capability ${slug} cannot have ${key} > 0; use needs_review instead`);
+                }
+            }
+        }
+    }
+    return data;
+}
+
+function createProgress(manifest, capability = null) {
+    return {
+        schema_version: PROGRESS_SCHEMA_VERSION,
+        system: manifest.name,
+        mode: capability ? 'targeted' : 'full',
+        target: capability || null,
+        started_at: nowIso(),
+        updated_at: nowIso(),
+        status: 'pending',
+        capabilities: {}
+    };
+}
+
+function readProgress(workspaceRoot, manifest, capability = null) {
+    const filePath = progressPath(workspaceRoot, manifest, capability);
+    const data = readJsonFile(filePath, `${manifest.spec_root}/${META_DIR}/${progressFileName(capability)}`);
+    if (!data) return null;
+    if (data.schema_version !== PROGRESS_SCHEMA_VERSION) {
+        throw new Error(`Unsupported reverse progress schema_version: ${data.schema_version}`);
+    }
+    return data;
+}
+
+function ensureProgress(workspaceRoot, manifest, capability = null, options = {}) {
+    ensureMetaRoot(workspaceRoot, manifest);
+    const filePath = progressPath(workspaceRoot, manifest, capability);
+    const existing = readProgress(workspaceRoot, manifest, capability);
+    if (existing && !options.reset) {
+        const sameMode = existing.mode === (capability ? 'targeted' : 'full');
+        const sameTarget = (existing.target || null) === (capability || null);
+        if (sameMode && sameTarget && existing.status !== 'completed') {
+            return { path: filePath, progress: existing, created: false, resumed: true };
+        }
+        if (sameMode && sameTarget && existing.status === 'completed') {
+            return { path: filePath, progress: existing, created: false, resumed: false, completed: true };
+        }
+    }
+    const progress = createProgress(manifest, capability);
+    fs.writeFileSync(filePath, JSON.stringify(progress, null, 2) + '\n', 'utf8');
+    return { path: filePath, progress, created: true, resumed: false };
+}
+
+function pathMatches(changedFile, sourcePath) {
+    const changed = portable(changedFile).replace(/^\.\//, '');
+    const source = portable(sourcePath).replace(/^\.\//, '').replace(/\/$/, '');
+    return changed === source || changed.startsWith(source + '/') || source.startsWith(changed + '/');
+}
+
+function changedFilesSince(repoRoot, baseCommit, options = {}) {
+    const head = getRepoHead(repoRoot, options);
+    if (!head.ok) return { ok: false, error: head.error };
+
+    const ancestry = runGit(repoRoot, ['cat-file', '-e', `${baseCommit}^{commit}`], options);
+    if (!ancestry.ok) {
+        return { ok: false, commit: head.commit, error: `verified commit is unavailable locally: ${baseCommit}` };
+    }
+
+    const changed = new Set();
+    if (head.commit !== baseCommit) {
+        const diff = runGit(repoRoot, ['diff', '--name-only', '--no-renames', `${baseCommit}..${head.commit}`], options);
+        if (!diff.ok) return { ok: false, commit: head.commit, error: diff.error };
+        for (const file of diff.stdout ? diff.stdout.split(/\r?\n/).filter(Boolean) : []) changed.add(portable(file));
+    }
+
+    for (const args of [
+        ['diff', '--name-only', '--no-renames', 'HEAD'],
+        ['diff', '--name-only', '--no-renames', '--cached'],
+        ['ls-files', '--others', '--exclude-standard']
+    ]) {
+        const result = runGit(repoRoot, args, options);
+        if (!result.ok) return { ok: false, commit: head.commit, error: result.error };
+        for (const file of result.stdout ? result.stdout.split(/\r?\n/).filter(Boolean) : []) changed.add(portable(file));
+    }
+
+    return { ok: true, commit: head.commit, changed: [...changed].sort() };
+}
+
+function checkSpecDrift(workspaceRoot, manifest, verification, options = {}) {
+    validateVerification(manifest, verification);
+    const repoStates = {};
+    for (const repo of manifest.repos) {
+        const verified = verification.repositories[repo.name];
+        const repoRoot = path.resolve(workspaceRoot, repo.path);
+        const head = getRepoHead(repoRoot, options);
+        repoStates[repo.name] = head.ok
+            ? { ok: true, path: repo.path, verified_commit: verified.commit, commit: head.commit }
+            : { ok: false, path: repo.path, verified_commit: verified.commit, error: head.error };
+    }
+
+    const capabilities = {};
+    const deltaCache = new Map();
+    for (const [slug, capability] of Object.entries(verification.capabilities)) {
+        if (capability.status !== 'verified') {
+            capabilities[slug] = {
+                status: capability.status,
+                stale: true,
+                reason: `verification status is ${capability.status}`,
+                changed_files: {}
+            };
+            continue;
+        }
+
+        let stale = false;
+        let unknown = false;
+        const changedFiles = {};
+        const reasons = [];
+
+        for (const repo of manifest.repos) {
+            const repoState = repoStates[repo.name];
+            const sourcePaths = normalizeSourcePaths((capability.source_paths || {})[repo.name]);
+            if (sourcePaths.length === 0) continue;
+
+            if (!repoState || !repoState.ok) {
+                unknown = true;
+                reasons.push(`${repo.name}: ${repoState ? repoState.error : 'missing repository state'}`);
+                continue;
+            }
+
+            const baseline = (capability.verified_commits || {})[repo.name]
+                || verification.repositories[repo.name].commit;
+            const repoRoot = path.resolve(workspaceRoot, repo.path);
+            const cacheKey = `${repo.name}:${baseline}`;
+            let delta = deltaCache.get(cacheKey);
+            if (!delta) {
+                delta = changedFilesSince(repoRoot, baseline, options);
+                deltaCache.set(cacheKey, delta);
+            }
+            if (!delta.ok) {
+                unknown = true;
+                reasons.push(`${repo.name}: ${delta.error}`);
+                continue;
+            }
+
+            const relevant = delta.changed.filter(file => sourcePaths.some(source => pathMatches(file, source)));
+            if (relevant.length > 0) {
+                stale = true;
+                changedFiles[repo.name] = relevant;
+            }
+        }
+
+        capabilities[slug] = {
+            status: unknown ? 'unknown' : (stale ? 'stale' : 'current'),
+            stale: stale || unknown,
+            reason: reasons.join('; ') || null,
+            changed_files: changedFiles
+        };
+    }
+
+    return {
+        checked_at: nowIso(),
+        repositories: repoStates,
+        capabilities,
+        stale_count: Object.values(capabilities).filter(item => item.stale).length
+    };
+}
+
+function formatDriftReport(report) {
+    const lines = ['System spec drift check', ''];
+    for (const [slug, result] of Object.entries(report.capabilities)) {
+        const marker = result.status === 'current' ? 'OK' : result.status.toUpperCase();
+        lines.push(`${marker} ${slug}`);
+        if (result.reason) lines.push(`  ${result.reason}`);
+        for (const [repoName, files] of Object.entries(result.changed_files || {})) {
+            lines.push(`  ${repoName}: ${files.length} relevant changed file(s)`);
+            for (const file of files.slice(0, 10)) lines.push(`    - ${file}`);
+            if (files.length > 10) lines.push(`    - ... ${files.length - 10} more`);
+        }
+    }
+    lines.push('');
+    lines.push(`Potentially stale/unknown capabilities: ${report.stale_count}`);
+    return lines.join('\n');
+}
+
+module.exports = {
+    META_DIR,
+    VERIFICATION_FILE,
+    REVIEW_FILE,
+    PROGRESS_FILE,
+    VERIFICATION_SCHEMA_VERSION,
+    PROGRESS_SCHEMA_VERSION,
+    metaRoot,
+    verificationPath,
+    reviewPath,
+    progressSlug,
+    progressFileName,
+    progressPath,
+    ensureMetaRoot,
+    getRepoHead,
+    captureRepoHeads,
+    readVerification,
+    validateVerification,
+    createProgress,
+    readProgress,
+    ensureProgress,
+    normalizeSourcePath,
+    normalizeSourcePaths,
+    pathMatches,
+    changedFilesSince,
+    checkSpecDrift,
+    formatDriftReport
+};