lightspec 0.1.1

package/dist/commands/validate.js

@@ -0,0 +1,294 @@
+import ora from 'ora';
+import path from 'path';
+import { Validator } from '../core/validation/validator.js';
+import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
+import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
+import { nearestMatches } from '../utils/match.js';
+export class ValidateCommand {
+    async execute(itemName, options = {}) {
+        const interactive = isInteractive(options);
+        // Handle bulk flags first
+        if (options.all || options.changes || options.specs) {
+            await this.runBulkValidation({
+                changes: !!options.all || !!options.changes,
+                specs: !!options.all || !!options.specs,
+            }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
+            return;
+        }
+        // No item and no flags
+        if (!itemName) {
+            if (interactive) {
+                await this.runInteractiveSelector({ strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
+                return;
+            }
+            this.printNonInteractiveHint();
+            process.exitCode = 1;
+            return;
+        }
+        // Direct item validation with type detection or override
+        const typeOverride = this.normalizeType(options.type);
+        await this.validateDirectItem(itemName, { typeOverride, strict: !!options.strict, json: !!options.json });
+    }
+    normalizeType(value) {
+        if (!value)
+            return undefined;
+        const v = value.toLowerCase();
+        if (v === 'change' || v === 'spec')
+            return v;
+        return undefined;
+    }
+    async runInteractiveSelector(opts) {
+        const { select } = await import('@inquirer/prompts');
+        const choice = await select({
+            message: 'What would you like to validate?',
+            choices: [
+                { name: 'All (changes + specs)', value: 'all' },
+                { name: 'All changes', value: 'changes' },
+                { name: 'All specs', value: 'specs' },
+                { name: 'Pick a specific change or spec', value: 'one' },
+            ],
+        });
+        if (choice === 'all')
+            return this.runBulkValidation({ changes: true, specs: true }, opts);
+        if (choice === 'changes')
+            return this.runBulkValidation({ changes: true, specs: false }, opts);
+        if (choice === 'specs')
+            return this.runBulkValidation({ changes: false, specs: true }, opts);
+        // one
+        const [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+        const items = [];
+        items.push(...changes.map(id => ({ name: `change/${id}`, value: { type: 'change', id } })));
+        items.push(...specs.map(id => ({ name: `spec/${id}`, value: { type: 'spec', id } })));
+        if (items.length === 0) {
+            console.error('No items found to validate.');
+            process.exitCode = 1;
+            return;
+        }
+        const picked = await select({ message: 'Pick an item', choices: items });
+        await this.validateByType(picked.type, picked.id, opts);
+    }
+    printNonInteractiveHint() {
+        console.error('Nothing to validate. Try one of:');
+        console.error('  lightspec validate --all');
+        console.error('  lightspec validate --changes');
+        console.error('  lightspec validate --specs');
+        console.error('  lightspec validate <item-name>');
+        console.error('Or run in an interactive terminal.');
+    }
+    async validateDirectItem(itemName, opts) {
+        const [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+        const isChange = changes.includes(itemName);
+        const isSpec = specs.includes(itemName);
+        const type = opts.typeOverride ?? (isChange ? 'change' : isSpec ? 'spec' : undefined);
+        if (!type) {
+            console.error(`Unknown item '${itemName}'`);
+            const suggestions = nearestMatches(itemName, [...changes, ...specs]);
+            if (suggestions.length)
+                console.error(`Did you mean: ${suggestions.join(', ')}?`);
+            process.exitCode = 1;
+            return;
+        }
+        if (!opts.typeOverride && isChange && isSpec) {
+            console.error(`Ambiguous item '${itemName}' matches both a change and a spec.`);
+            console.error('Pass --type change|spec, or use: lightspec change validate / lightspec spec validate');
+            process.exitCode = 1;
+            return;
+        }
+        await this.validateByType(type, itemName, opts);
+    }
+    async validateByType(type, id, opts) {
+        const validator = new Validator(opts.strict);
+        if (type === 'change') {
+            const changeDir = path.join(process.cwd(), 'lightspec', 'changes', id);
+            const start = Date.now();
+            const report = await validator.validateChangeDeltaSpecs(changeDir);
+            const durationMs = Date.now() - start;
+            this.printReport('change', id, report, durationMs, opts.json);
+            // Non-zero exit if invalid (keeps enriched output test semantics)
+            process.exitCode = report.valid ? 0 : 1;
+            return;
+        }
+        const file = path.join(process.cwd(), 'lightspec', 'specs', id, 'spec.md');
+        const start = Date.now();
+        const report = await validator.validateSpec(file);
+        const durationMs = Date.now() - start;
+        this.printReport('spec', id, report, durationMs, opts.json);
+        process.exitCode = report.valid ? 0 : 1;
+    }
+    printReport(type, id, report, durationMs, json) {
+        if (json) {
+            const out = { items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }], summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } }, version: '1.0' };
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (report.valid) {
+            console.log(`${type === 'change' ? 'Change' : 'Specification'} '${id}' is valid`);
+        }
+        else {
+            console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
+            for (const issue of report.issues) {
+                const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
+                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+            }
+            this.printNextSteps(type);
+        }
+    }
+    printNextSteps(type) {
+        const bullets = [];
+        if (type === 'change') {
+            bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
+            bullets.push('- Each requirement MUST include at least one #### Scenario: block');
+            bullets.push('- Debug parsed deltas: lightspec change show <id> --json --deltas-only');
+        }
+        else {
+            bullets.push('- Ensure spec includes ## Purpose and ## Requirements sections');
+            bullets.push('- Each requirement MUST include at least one #### Scenario: block');
+            bullets.push('- Re-run with --json to see structured report');
+        }
+        console.error('Next steps:');
+        bullets.forEach(b => console.error(`  ${b}`));
+    }
+    async runBulkValidation(scope, opts) {
+        const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
+        const [changeIds, specIds] = await Promise.all([
+            scope.changes ? getActiveChangeIds() : Promise.resolve([]),
+            scope.specs ? getSpecIds() : Promise.resolve([]),
+        ]);
+        const DEFAULT_CONCURRENCY = 6;
+        const maxSuggestions = 5; // used by nearestMatches
+        const concurrency = normalizeConcurrency(opts.concurrency) ?? normalizeConcurrency(process.env.LIGHTSPEC_CONCURRENCY) ?? DEFAULT_CONCURRENCY;
+        const validator = new Validator(opts.strict);
+        const queue = [];
+        for (const id of changeIds) {
+            queue.push(async () => {
+                const start = Date.now();
+                const changeDir = path.join(process.cwd(), 'lightspec', 'changes', id);
+                const report = await validator.validateChangeDeltaSpecs(changeDir);
+                const durationMs = Date.now() - start;
+                return { id, type: 'change', valid: report.valid, issues: report.issues, durationMs };
+            });
+        }
+        for (const id of specIds) {
+            queue.push(async () => {
+                const start = Date.now();
+                const file = path.join(process.cwd(), 'lightspec', 'specs', id, 'spec.md');
+                const report = await validator.validateSpec(file);
+                const durationMs = Date.now() - start;
+                return { id, type: 'spec', valid: report.valid, issues: report.issues, durationMs };
+            });
+        }
+        if (queue.length === 0) {
+            spinner?.stop();
+            const summary = {
+                totals: { items: 0, passed: 0, failed: 0 },
+                byType: {
+                    ...(scope.changes ? { change: { items: 0, passed: 0, failed: 0 } } : {}),
+                    ...(scope.specs ? { spec: { items: 0, passed: 0, failed: 0 } } : {}),
+                },
+            };
+            if (opts.json) {
+                const out = { items: [], summary, version: '1.0' };
+                console.log(JSON.stringify(out, null, 2));
+            }
+            else {
+                console.log('No items found to validate.');
+            }
+            process.exitCode = 0;
+            return;
+        }
+        const results = [];
+        let index = 0;
+        let running = 0;
+        let passed = 0;
+        let failed = 0;
+        await new Promise((resolve) => {
+            const next = () => {
+                while (running < concurrency && index < queue.length) {
+                    const currentIndex = index++;
+                    const task = queue[currentIndex];
+                    running++;
+                    if (spinner)
+                        spinner.text = `Validating (${currentIndex + 1}/${queue.length})...`;
+                    task()
+                        .then(res => {
+                        results.push(res);
+                        if (res.valid)
+                            passed++;
+                        else
+                            failed++;
+                    })
+                        .catch((error) => {
+                        const message = error?.message || 'Unknown error';
+                        const res = { id: getPlannedId(currentIndex, changeIds, specIds) ?? 'unknown', type: getPlannedType(currentIndex, changeIds, specIds) ?? 'change', valid: false, issues: [{ level: 'ERROR', path: 'file', message }], durationMs: 0 };
+                        results.push(res);
+                        failed++;
+                    })
+                        .finally(() => {
+                        running--;
+                        if (index >= queue.length && running === 0)
+                            resolve();
+                        else
+                            next();
+                    });
+                }
+            };
+            next();
+        });
+        spinner?.stop();
+        results.sort((a, b) => a.id.localeCompare(b.id));
+        const summary = {
+            totals: { items: results.length, passed, failed },
+            byType: {
+                ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
+                ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
+            },
+        };
+        if (opts.json) {
+            const out = { items: results, summary, version: '1.0' };
+            console.log(JSON.stringify(out, null, 2));
+        }
+        else {
+            for (const res of results) {
+                if (res.valid)
+                    console.log(`✓ ${res.type}/${res.id}`);
+                else
+                    console.error(`✗ ${res.type}/${res.id}`);
+            }
+            console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
+        }
+        process.exitCode = failed > 0 ? 1 : 0;
+    }
+}
+function summarizeType(results, type) {
+    const filtered = results.filter(r => r.type === type);
+    const items = filtered.length;
+    const passed = filtered.filter(r => r.valid).length;
+    const failed = items - passed;
+    return { items, passed, failed };
+}
+function normalizeConcurrency(value) {
+    if (!value)
+        return undefined;
+    const n = parseInt(value, 10);
+    if (Number.isNaN(n) || n <= 0)
+        return undefined;
+    return n;
+}
+function getPlannedId(index, changeIds, specIds) {
+    const totalChanges = changeIds.length;
+    if (index < totalChanges)
+        return changeIds[index];
+    const specIndex = index - totalChanges;
+    return specIds[specIndex];
+}
+function getPlannedType(index, changeIds, specIds) {
+    const totalChanges = changeIds.length;
+    if (index < totalChanges)
+        return 'change';
+    const specIndex = index - totalChanges;
+    if (specIndex >= 0 && specIndex < specIds.length)
+        return 'spec';
+    return undefined;
+}
+//# sourceMappingURL=validate.js.map

package/dist/core/archive.d.ts

@@ -0,0 +1,11 @@
+export declare class ArchiveCommand {
+    execute(changeName?: string, options?: {
+        yes?: boolean;
+        skipSpecs?: boolean;
+        noValidate?: boolean;
+        validate?: boolean;
+    }): Promise<void>;
+    private selectChange;
+    private getArchiveDate;
+}
+//# sourceMappingURL=archive.d.ts.map

package/dist/core/archive.js

@@ -0,0 +1,280 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
+import { Validator } from './validation/validator.js';
+import chalk from 'chalk';
+import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, } from './specs-apply.js';
+export class ArchiveCommand {
+    async execute(changeName, options = {}) {
+        const targetPath = '.';
+        const changesDir = path.join(targetPath, 'lightspec', 'changes');
+        const archiveDir = path.join(changesDir, 'archive');
+        const mainSpecsDir = path.join(targetPath, 'lightspec', 'specs');
+        // Check if changes directory exists
+        try {
+            await fs.access(changesDir);
+        }
+        catch {
+            throw new Error("No LightSpec changes directory found. Run 'lightspec init' first.");
+        }
+        // Get change name interactively if not provided
+        if (!changeName) {
+            const selectedChange = await this.selectChange(changesDir);
+            if (!selectedChange) {
+                console.log('No change selected. Aborting.');
+                return;
+            }
+            changeName = selectedChange;
+        }
+        const changeDir = path.join(changesDir, changeName);
+        // Verify change exists
+        try {
+            const stat = await fs.stat(changeDir);
+            if (!stat.isDirectory()) {
+                throw new Error(`Change '${changeName}' not found.`);
+            }
+        }
+        catch {
+            throw new Error(`Change '${changeName}' not found.`);
+        }
+        const skipValidation = options.validate === false || options.noValidate === true;
+        // Validate specs and change before archiving
+        if (!skipValidation) {
+            const validator = new Validator();
+            let hasValidationErrors = false;
+            // Validate proposal.md (non-blocking unless strict mode desired in future)
+            const changeFile = path.join(changeDir, 'proposal.md');
+            try {
+                await fs.access(changeFile);
+                const changeReport = await validator.validateChange(changeFile);
+                // Proposal validation is informative only (do not block archive)
+                if (!changeReport.valid) {
+                    console.log(chalk.yellow(`\nProposal warnings in proposal.md (non-blocking):`));
+                    for (const issue of changeReport.issues) {
+                        const symbol = issue.level === 'ERROR' ? '⚠' : (issue.level === 'WARNING' ? '⚠' : 'ℹ');
+                        console.log(chalk.yellow(`  ${symbol} ${issue.message}`));
+                    }
+                }
+            }
+            catch {
+                // Change file doesn't exist, skip validation
+            }
+            // Validate delta-formatted spec files under the change directory if present
+            const changeSpecsDir = path.join(changeDir, 'specs');
+            let hasDeltaSpecs = false;
+            try {
+                const candidates = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+                for (const c of candidates) {
+                    if (c.isDirectory()) {
+                        try {
+                            const candidatePath = path.join(changeSpecsDir, c.name, 'spec.md');
+                            await fs.access(candidatePath);
+                            const content = await fs.readFile(candidatePath, 'utf-8');
+                            if (/^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/m.test(content)) {
+                                hasDeltaSpecs = true;
+                                break;
+                            }
+                        }
+                        catch { }
+                    }
+                }
+            }
+            catch { }
+            if (hasDeltaSpecs) {
+                const deltaReport = await validator.validateChangeDeltaSpecs(changeDir);
+                if (!deltaReport.valid) {
+                    hasValidationErrors = true;
+                    console.log(chalk.red(`\nValidation errors in change delta specs:`));
+                    for (const issue of deltaReport.issues) {
+                        if (issue.level === 'ERROR') {
+                            console.log(chalk.red(`  ✗ ${issue.message}`));
+                        }
+                        else if (issue.level === 'WARNING') {
+                            console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                        }
+                    }
+                }
+            }
+            if (hasValidationErrors) {
+                console.log(chalk.red('\nValidation failed. Please fix the errors before archiving.'));
+                console.log(chalk.yellow('To skip validation (not recommended), use --no-validate flag.'));
+                return;
+            }
+        }
+        else {
+            // Log warning when validation is skipped
+            const timestamp = new Date().toISOString();
+            if (!options.yes) {
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: chalk.yellow('⚠️  WARNING: Skipping validation may archive invalid specs. Continue? (y/N)'),
+                    default: false
+                });
+                if (!proceed) {
+                    console.log('Archive cancelled.');
+                    return;
+                }
+            }
+            else {
+                console.log(chalk.yellow(`\n⚠️  WARNING: Skipping validation may archive invalid specs.`));
+            }
+            console.log(chalk.yellow(`[${timestamp}] Validation skipped for change: ${changeName}`));
+            console.log(chalk.yellow(`Affected files: ${changeDir}`));
+        }
+        // Show progress and check for incomplete tasks
+        const progress = await getTaskProgressForChange(changesDir, changeName);
+        const status = formatTaskStatus(progress);
+        console.log(`Task status: ${status}`);
+        const incompleteTasks = Math.max(progress.total - progress.completed, 0);
+        if (incompleteTasks > 0) {
+            if (!options.yes) {
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
+                    default: false
+                });
+                if (!proceed) {
+                    console.log('Archive cancelled.');
+                    return;
+                }
+            }
+            else {
+                console.log(`Warning: ${incompleteTasks} incomplete task(s) found. Continuing due to --yes flag.`);
+            }
+        }
+        // Handle spec updates unless skipSpecs flag is set
+        if (options.skipSpecs) {
+            console.log('Skipping spec updates (--skip-specs flag provided).');
+        }
+        else {
+            // Find specs to update
+            const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
+            if (specUpdates.length > 0) {
+                console.log('\nSpecs to update:');
+                for (const update of specUpdates) {
+                    const status = update.exists ? 'update' : 'create';
+                    const capability = path.basename(path.dirname(update.target));
+                    console.log(`  ${capability}: ${status}`);
+                }
+                let shouldUpdateSpecs = true;
+                if (!options.yes) {
+                    const { confirm } = await import('@inquirer/prompts');
+                    shouldUpdateSpecs = await confirm({
+                        message: 'Proceed with spec updates?',
+                        default: true
+                    });
+                    if (!shouldUpdateSpecs) {
+                        console.log('Skipping spec updates. Proceeding with archive.');
+                    }
+                }
+                if (shouldUpdateSpecs) {
+                    // Prepare all updates first (validation pass, no writes)
+                    const prepared = [];
+                    try {
+                        for (const update of specUpdates) {
+                            const built = await buildUpdatedSpec(update, changeName);
+                            prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+                        }
+                    }
+                    catch (err) {
+                        console.log(String(err.message || err));
+                        console.log('Aborted. No files were changed.');
+                        return;
+                    }
+                    // All validations passed; pre-validate rebuilt full spec and then write files and display counts
+                    let totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+                    for (const p of prepared) {
+                        const specName = path.basename(path.dirname(p.update.target));
+                        if (!skipValidation) {
+                            const report = await new Validator().validateSpecContent(specName, p.rebuilt);
+                            if (!report.valid) {
+                                console.log(chalk.red(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`));
+                                for (const issue of report.issues) {
+                                    if (issue.level === 'ERROR')
+                                        console.log(chalk.red(`  ✗ ${issue.message}`));
+                                    else if (issue.level === 'WARNING')
+                                        console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                                }
+                                console.log('Aborted. No files were changed.');
+                                return;
+                            }
+                        }
+                        await writeUpdatedSpec(p.update, p.rebuilt, p.counts);
+                        totals.added += p.counts.added;
+                        totals.modified += p.counts.modified;
+                        totals.removed += p.counts.removed;
+                        totals.renamed += p.counts.renamed;
+                    }
+                    console.log(`Totals: + ${totals.added}, ~ ${totals.modified}, - ${totals.removed}, → ${totals.renamed}`);
+                    console.log('Specs updated successfully.');
+                }
+            }
+        }
+        // Create archive directory with date prefix
+        const archiveName = `${this.getArchiveDate()}-${changeName}`;
+        const archivePath = path.join(archiveDir, archiveName);
+        // Check if archive already exists
+        try {
+            await fs.access(archivePath);
+            throw new Error(`Archive '${archiveName}' already exists.`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        // Create archive directory if needed
+        await fs.mkdir(archiveDir, { recursive: true });
+        // Move change to archive
+        await fs.rename(changeDir, archivePath);
+        console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+    }
+    async selectChange(changesDir) {
+        const { select } = await import('@inquirer/prompts');
+        // Get all directories in changes (excluding archive)
+        const entries = await fs.readdir(changesDir, { withFileTypes: true });
+        const changeDirs = entries
+            .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+            .map(entry => entry.name)
+            .sort();
+        if (changeDirs.length === 0) {
+            console.log('No active changes found.');
+            return null;
+        }
+        // Build choices with progress inline to avoid duplicate lists
+        let choices = changeDirs.map(name => ({ name, value: name }));
+        try {
+            const progressList = [];
+            for (const id of changeDirs) {
+                const progress = await getTaskProgressForChange(changesDir, id);
+                const status = formatTaskStatus(progress);
+                progressList.push({ id, status });
+            }
+            const nameWidth = Math.max(...progressList.map(p => p.id.length));
+            choices = progressList.map(p => ({
+                name: `${p.id.padEnd(nameWidth)}     ${p.status}`,
+                value: p.id
+            }));
+        }
+        catch {
+            // If anything fails, fall back to simple names
+            choices = changeDirs.map(name => ({ name, value: name }));
+        }
+        try {
+            const answer = await select({
+                message: 'Select a change to archive',
+                choices
+            });
+            return answer;
+        }
+        catch (error) {
+            // User cancelled (Ctrl+C)
+            return null;
+        }
+    }
+    getArchiveDate() {
+        // Returns date in YYYY-MM-DD format
+        return new Date().toISOString().split('T')[0];
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/core/completions/command-registry.d.ts

@@ -0,0 +1,7 @@
+import { CommandDefinition } from './types.js';
+/**
+ * Registry of all LightSpec CLI commands with their flags and metadata.
+ * This registry is used to generate shell completion scripts.
+ */
+export declare const COMMAND_REGISTRY: CommandDefinition[];
+//# sourceMappingURL=command-registry.d.ts.map