@spekn/cli 1.0.0 → 1.0.1

package/dist/commands/spec/lint.js

@@ -1,499 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-/**
- * spec-lint CLI Tool
- *
- * Validate specification markdown quality and structure.
- *
- * Usage: npm run spec-lint <spec-file-path>
- * Example: npm run spec-lint specs/DECISIONS.md
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.main = main;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const agents_1 = require("@spekn/agents");
-const shared_1 = require("@spekn/shared");
-const cli_runtime_1 = require("../../utils/cli-runtime");
-function parseArgs(args) {
-    const options = {};
-    let filePath;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--verbose" || arg === "-v") {
-            options.verbose = true;
-        }
-        else if (arg === "--fix" || arg === "-f") {
-            options.fix = true;
-        }
-        else if (!arg.startsWith("-")) {
-            filePath = arg;
-        }
-    }
-    if (!filePath) {
-        throw new Error("missing required argument: <spec-file-path>");
-    }
-    return { filePath, options };
-}
-function printHelp() {
-    console.log(`
-spec-lint - Validate specification markdown quality
-
-USAGE:
-  npm run spec-lint <spec-file-path> [OPTIONS]
-
-ARGUMENTS:
-  <spec-file-path>    Path to the specification markdown file
-
-OPTIONS:
-  -v, --verbose       Show detailed output and suggestions
-  -f, --fix           Auto-fix deterministic anchor formatting issues
-  -h, --help          Show this help message
-
-LINTING RULES:
-  frontmatter-required  Specification has valid YAML frontmatter
-  anchor-naming         Anchors follow naming convention (lowercase, dots)
-  anchor-duplicates     No duplicate anchors
-  anchor-acceptance     All anchors have acceptance criteria
-  dependency-valid      Dependencies reference valid anchors
-  markdown-quality      Basic markdown quality checks
-
-EXAMPLES:
-  npm run spec-lint specs/SPECIFICATION.md
-  npm run spec-lint specs/DECISIONS.md --verbose
-`);
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function normalizeAnchorForFix(anchor) {
-    return anchor
-        .trim()
-        .toLowerCase()
-        .replace(/\s+/g, "-")
-        .replace(/[^a-z0-9._-]/g, "-")
-        .replace(/\.\./g, ".")
-        .replace(/^\./, "")
-        .replace(/\.$/, "");
-}
-function applyDeterministicFixes(content) {
-    const anchors = (0, agents_1.extractAnchors)(content);
-    const uniqueAnchors = Array.from(new Set(anchors.map((a) => a.anchor)));
-    let nextContent = content;
-    let fixesApplied = 0;
-    const replaceWithCount = (input, pattern, replacement) => {
-        let count = 0;
-        const output = input.replace(pattern, () => {
-            count += 1;
-            return replacement;
-        });
-        return { output, count };
-    };
-    for (const anchor of uniqueAnchors) {
-        const normalized = normalizeAnchorForFix(anchor);
-        if (!normalized || normalized === anchor) {
-            continue;
-        }
-        const escaped = escapeRegExp(anchor);
-        const bracket = replaceWithCount(nextContent, new RegExp(`\\[${escaped}\\]`, "g"), `[${normalized}]`);
-        nextContent = bracket.output;
-        fixesApplied += bracket.count;
-        const prefixed = replaceWithCount(nextContent, new RegExp(`spec:${escaped}\\b`, "gi"), `spec:${normalized}`);
-        nextContent = prefixed.output;
-        fixesApplied += prefixed.count;
-        const hashDeps = replaceWithCount(nextContent, new RegExp(`#${escaped}\\b`, "g"), `#${normalized}`);
-        nextContent = hashDeps.output;
-        fixesApplied += hashDeps.count;
-    }
-    return { content: nextContent, fixesApplied };
-}
-function checkAnchorNaming(anchors) {
-    const issues = [];
-    anchors.forEach((anchor) => {
-        // Check lowercase
-        if (anchor.anchor !== anchor.anchor.toLowerCase()) {
-            issues.push({
-                severity: "error",
-                rule: "anchor-naming",
-                message: "Anchor should be lowercase",
-                anchor: anchor.anchor,
-                line: anchor.lineNumber,
-                suggestion: anchor.anchor.toLowerCase(),
-            });
-        }
-        // Check valid characters (only lowercase letters, numbers, dots, hyphens)
-        if (!anchor.anchor.match(/^[a-z0-9._-]+$/)) {
-            issues.push({
-                severity: "error",
-                rule: "anchor-naming",
-                message: "Anchor contains invalid characters (only a-z, 0-9, ., -, _ allowed)",
-                anchor: anchor.anchor,
-                line: anchor.lineNumber,
-            });
-        }
-        // Check for double dots or leading/trailing dots
-        if (anchor.anchor.match(/\.\./)) {
-            issues.push({
-                severity: "warning",
-                rule: "anchor-naming",
-                message: "Anchor contains consecutive dots",
-                anchor: anchor.anchor,
-                line: anchor.lineNumber,
-            });
-        }
-        if (anchor.anchor.startsWith(".") || anchor.anchor.endsWith(".")) {
-            issues.push({
-                severity: "warning",
-                rule: "anchor-naming",
-                message: "Anchor should not start or end with a dot",
-                anchor: anchor.anchor,
-                line: anchor.lineNumber,
-            });
-        }
-        // Recommend dot notation for hierarchical anchors
-        if (anchor.anchor.includes("_") && !anchor.anchor.includes(".")) {
-            issues.push({
-                severity: "info",
-                rule: "anchor-naming",
-                message: "Consider using dot notation for hierarchical structure",
-                anchor: anchor.anchor,
-                line: anchor.lineNumber,
-                suggestion: anchor.anchor.replace(/_/g, "."),
-            });
-        }
-    });
-    return issues;
-}
-function checkDuplicateAnchors(anchors) {
-    const issues = [];
-    const anchorMap = new Map();
-    anchors.forEach((anchor) => {
-        const normalized = anchor.anchor.toLowerCase();
-        if (!anchorMap.has(normalized)) {
-            anchorMap.set(normalized, []);
-        }
-        anchorMap.get(normalized).push(anchor.lineNumber);
-    });
-    anchorMap.forEach((lines, anchor) => {
-        if (lines.length > 1) {
-            issues.push({
-                severity: "error",
-                rule: "anchor-duplicates",
-                message: `Duplicate anchor found on lines: ${lines.join(", ")}`,
-                anchor,
-            });
-        }
-    });
-    return issues;
-}
-function checkAcceptanceCriteria(content, anchors) {
-    const issues = [];
-    anchors.forEach((anchor) => {
-        const anchorContent = (0, agents_1.extractAnchorContent)(anchor.anchor, content);
-        if (!anchorContent)
-            return;
-        // Check for acceptance criteria section
-        const hasAcceptanceCriteria = anchorContent.match(/\*\*Acceptance Criteria\*\*:|##\s*Acceptance Criteria|###\s*Acceptance Criteria/i);
-        if (!hasAcceptanceCriteria) {
-            issues.push({
-                severity: "warning",
-                rule: "anchor-acceptance",
-                message: "Anchor lacks explicit acceptance criteria section",
-                anchor: anchor.anchor,
-                line: anchor.lineNumber,
-            });
-        }
-    });
-    return issues;
-}
-function checkDependencyValidity(content, anchors) {
-    const issues = [];
-    const validAnchors = (0, agents_1.getValidAnchors)(content);
-    anchors.forEach((anchor) => {
-        const anchorContent = (0, agents_1.extractAnchorContent)(anchor.anchor, content);
-        if (!anchorContent)
-            return;
-        // Look for dependency references
-        const dependencyMatch = anchorContent.match(/\*\*Dependencies\*\*:([^\n]+)/i);
-        if (dependencyMatch) {
-            const dependencyText = dependencyMatch[1];
-            const dependencyAnchors = dependencyText.match(/#[a-z0-9._-]+/gi);
-            if (dependencyAnchors) {
-                dependencyAnchors.forEach((dep) => {
-                    const depNormalized = dep.replace(/^#/, "").toLowerCase();
-                    const isValid = validAnchors.some((valid) => valid.toLowerCase() === depNormalized);
-                    if (!isValid) {
-                        issues.push({
-                            severity: "error",
-                            rule: "dependency-valid",
-                            message: `Dependency references non-existent anchor: ${dep}`,
-                            anchor: anchor.anchor,
-                            line: anchor.lineNumber,
-                        });
-                    }
-                });
-            }
-        }
-    });
-    return issues;
-}
-function checkMarkdownQuality(content) {
-    const issues = [];
-    const lines = content.split("\n");
-    lines.forEach((line, index) => {
-        const lineNumber = index + 1;
-        // Check for trailing whitespace
-        if (line.endsWith(" ") || line.endsWith("\t")) {
-            issues.push({
-                severity: "info",
-                rule: "markdown-quality",
-                message: "Line has trailing whitespace",
-                line: lineNumber,
-            });
-        }
-        // Check for inconsistent heading markers
-        const headingMatch = line.match(/^(#{1,6})\s/);
-        if (headingMatch && line.includes("#", headingMatch[1].length + 1)) {
-            const afterHeading = line.substring(headingMatch[0].length);
-            if (!afterHeading.startsWith("#")) {
-                // Check if there's a # not at the start (could be an anchor)
-                if (afterHeading.includes("#") &&
-                    !afterHeading.match(/^#[a-z0-9._-]+/i)) {
-                    issues.push({
-                        severity: "warning",
-                        rule: "markdown-quality",
-                        message: "Unexpected # character in heading",
-                        line: lineNumber,
-                    });
-                }
-            }
-        }
-    });
-    return issues;
-}
-function checkFrontmatter(content) {
-    const issues = [];
-    const result = (0, shared_1.parseSpecificationFrontmatter)(content);
-    if (!result.hasFrontmatter) {
-        issues.push({
-            severity: "error",
-            rule: "frontmatter-required",
-            message: "Specification is missing required YAML frontmatter (delimited by --- markers)",
-        });
-        return issues;
-    }
-    if (result.errors?.length) {
-        for (const error of result.errors) {
-            issues.push({
-                severity: "error",
-                rule: "frontmatter-required",
-                message: `Frontmatter validation error: ${error}`,
-            });
-        }
-        return issues;
-    }
-    const fm = result.frontmatter;
-    if (!fm)
-        return issues;
-    // Check hint lengths
-    if (fm.hints) {
-        for (const [layer, hints] of Object.entries(fm.hints)) {
-            if (!hints)
-                continue;
-            for (let i = 0; i < hints.length; i++) {
-                if (hints[i].length > shared_1.HINT_MAX_LENGTH) {
-                    issues.push({
-                        severity: "error",
-                        rule: "frontmatter-required",
-                        message: `Hint hints.${layer}[${i}] exceeds ${shared_1.HINT_MAX_LENGTH} character limit (${hints[i].length} chars)`,
-                    });
-                }
-            }
-        }
-    }
-    // Check type-specific properties match declared type
-    const typeSpecific = ["capability", "architectural", "workflow", "operational"];
-    const present = typeSpecific.filter((t) => fm[t]);
-    if (present.length > 1) {
-        issues.push({
-            severity: "error",
-            rule: "frontmatter-required",
-            message: `Multiple type-specific properties found (${present.join(", ")}). Only one is allowed.`,
-        });
-    }
-    if (present.length === 1 && present[0] !== fm.type) {
-        issues.push({
-            severity: "warning",
-            rule: "frontmatter-required",
-            message: `Type-specific property "${present[0]}" does not match declared type "${fm.type}"`,
-        });
-    }
-    return issues;
-}
-function main(argv) {
-    const args = argv ?? process.argv.slice(2);
-    if ((0, cli_runtime_1.hasHelpFlag)(args)) {
-        printHelp();
-        return 0;
-    }
-    let filePath;
-    let options;
-    try {
-        ({ filePath, options } = parseArgs(args));
-    }
-    catch {
-        console.error("Error: Missing required argument <spec-file-path>");
-        printHelp();
-        return 1;
-    }
-    // Resolve file path
-    const resolvedPath = path.resolve(process.cwd(), filePath);
-    // Check if file exists
-    if (!fs.existsSync(resolvedPath)) {
-        console.error(`Error: File not found: ${resolvedPath}`);
-        return 1;
-    }
-    // Read file content
-    let content;
-    try {
-        content = fs.readFileSync(resolvedPath, "utf-8");
-    }
-    catch (error) {
-        console.error(`Error reading file: ${(0, cli_runtime_1.errorMessage)(error)}`);
-        return 1;
-    }
-    let fixSummary = null;
-    if (options.fix) {
-        const fixed = applyDeterministicFixes(content);
-        const fileModified = fixed.content !== content;
-        if (fileModified) {
-            fs.writeFileSync(resolvedPath, fixed.content, "utf-8");
-            content = fixed.content;
-        }
-        fixSummary = {
-            attempted: true,
-            fixesApplied: fixed.fixesApplied,
-            fileModified,
-        };
-    }
-    // Extract anchors
-    const anchors = (0, agents_1.extractAnchors)(content);
-    console.log(`\nLinting ${path.basename(filePath)}...`);
-    console.log(`Found ${anchors.length} anchor(s)\n`);
-    // Run all lint checks
-    const issues = [
-        ...checkFrontmatter(content),
-        ...checkAnchorNaming(anchors),
-        ...checkDuplicateAnchors(anchors),
-        ...checkAcceptanceCriteria(content, anchors),
-        ...checkDependencyValidity(content, anchors),
-        ...checkMarkdownQuality(content),
-    ];
-    // Group issues by severity
-    const errors = issues.filter((i) => i.severity === "error");
-    const warnings = issues.filter((i) => i.severity === "warning");
-    const infos = issues.filter((i) => i.severity === "info");
-    // Display results
-    if (issues.length === 0) {
-        console.log("✓ No issues found. Specification is clean!\n");
-        return 0;
-    }
-    if (errors.length > 0) {
-        console.log(`\n❌ Errors (${errors.length}):\n`);
-        errors.forEach((issue, index) => {
-            console.log(`${index + 1}. [${issue.rule}] ${issue.message}`);
-            if (issue.anchor)
-                console.log(`   Anchor: ${issue.anchor}`);
-            if (issue.line)
-                console.log(`   Line: ${issue.line}`);
-            if (issue.suggestion && options.verbose)
-                console.log(`   Suggestion: ${issue.suggestion}`);
-            console.log();
-        });
-    }
-    if (warnings.length > 0) {
-        console.log(`\n⚠️  Warnings (${warnings.length}):\n`);
-        warnings.forEach((issue, index) => {
-            console.log(`${index + 1}. [${issue.rule}] ${issue.message}`);
-            if (issue.anchor)
-                console.log(`   Anchor: ${issue.anchor}`);
-            if (issue.line)
-                console.log(`   Line: ${issue.line}`);
-            if (issue.suggestion && options.verbose)
-                console.log(`   Suggestion: ${issue.suggestion}`);
-            console.log();
-        });
-    }
-    if (infos.length > 0 && options.verbose) {
-        console.log(`\nℹ️  Info (${infos.length}):\n`);
-        infos.forEach((issue, index) => {
-            console.log(`${index + 1}. [${issue.rule}] ${issue.message}`);
-            if (issue.anchor)
-                console.log(`   Anchor: ${issue.anchor}`);
-            if (issue.line)
-                console.log(`   Line: ${issue.line}`);
-            if (issue.suggestion)
-                console.log(`   Suggestion: ${issue.suggestion}`);
-            console.log();
-        });
-    }
-    // Summary
-    console.log("Summary:");
-    console.log(`  Errors: ${errors.length}`);
-    console.log(`  Warnings: ${warnings.length}`);
-    console.log(`  Info: ${infos.length}`);
-    if (fixSummary?.attempted) {
-        console.log(`  Fixes applied: ${fixSummary.fixesApplied}`);
-        console.log(`  File modified: ${fixSummary.fileModified ? "yes" : "no"}`);
-    }
-    console.log();
-    // Exit with error code if there are errors
-    if (errors.length > 0) {
-        console.log("❌ Linting failed due to errors.\n");
-        return 1;
-    }
-    else if (warnings.length > 0) {
-        console.log("⚠️  Linting passed with warnings.\n");
-        return 0;
-    }
-    else {
-        console.log("✓ Linting passed.\n");
-        return 0;
-    }
-}
-if (require.main === module) {
-    void (0, cli_runtime_1.runCliMain)(main, { errorPrefix: "spec-lint failed" });
-}

package/dist/commands/spec/parse.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-/**
- * spec-parse CLI Tool
- *
- * Parse specification markdown and extract all valid anchors.
- *
- * Usage: npm run spec-parse <spec-file-path>
- * Example: npm run spec-parse specs/SPECIFICATION.md
- */
-declare function main(argv?: string[]): number;
-export { main };

package/dist/commands/spec/parse.js

@@ -1,162 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-/**
- * spec-parse CLI Tool
- *
- * Parse specification markdown and extract all valid anchors.
- *
- * Usage: npm run spec-parse <spec-file-path>
- * Example: npm run spec-parse specs/SPECIFICATION.md
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.main = main;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const agents_1 = require("@spekn/agents");
-const cli_runtime_1 = require("../../utils/cli-runtime");
-function parseArgs(args) {
-    const options = {};
-    let filePath;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--verbose" || arg === "-v") {
-            options.verbose = true;
-        }
-        else if (arg === "--json" || arg === "-j") {
-            options.json = true;
-        }
-        else if (!arg.startsWith("-")) {
-            filePath = arg;
-        }
-    }
-    if (!filePath) {
-        throw new Error("missing required argument: <spec-file-path>");
-    }
-    return { filePath, options };
-}
-function printHelp() {
-    console.log(`
-spec-parse - Parse specification markdown and extract anchors
-
-USAGE:
-  npm run spec-parse <spec-file-path> [OPTIONS]
-
-ARGUMENTS:
-  <spec-file-path>    Path to the specification markdown file
-
-OPTIONS:
-  -v, --verbose       Show detailed output
-  -j, --json          Output in JSON format
-  -h, --help          Show this help message
-
-EXAMPLES:
-  npm run spec-parse specs/SPECIFICATION.md
-  npm run spec-parse specs/WORKFLOW.md --json
-  npm run spec-parse specs/DECISIONS.md --verbose
-`);
-}
-function main(argv) {
-    const args = argv ?? process.argv.slice(2);
-    if ((0, cli_runtime_1.hasHelpFlag)(args)) {
-        printHelp();
-        return 0;
-    }
-    let filePath;
-    let options;
-    try {
-        ({ filePath, options } = parseArgs(args));
-    }
-    catch {
-        console.error("Error: Missing required argument <spec-file-path>");
-        printHelp();
-        return 1;
-    }
-    // Resolve file path
-    const resolvedPath = path.resolve(process.cwd(), filePath);
-    // Check if file exists
-    if (!fs.existsSync(resolvedPath)) {
-        console.error(`Error: File not found: ${resolvedPath}`);
-        return 1;
-    }
-    // Read file content
-    let content;
-    try {
-        content = fs.readFileSync(resolvedPath, "utf-8");
-    }
-    catch (error) {
-        console.error(`Error reading file: ${(0, cli_runtime_1.errorMessage)(error)}`);
-        return 1;
-    }
-    // Extract anchors
-    const anchors = (0, agents_1.extractAnchors)(content);
-    if (anchors.length === 0) {
-        console.log("No anchors found in the specification.");
-        return 0;
-    }
-    // Output results
-    if (options.json) {
-        console.log(JSON.stringify(anchors, null, 2));
-    }
-    else {
-        console.log(`\nFound ${anchors.length} anchor(s) in ${path.basename(filePath)}:\n`);
-        // Create table data
-        const tableData = anchors.map((anchor) => ({
-            Anchor: anchor.anchor,
-            Level: "H" + anchor.level,
-            Line: anchor.lineNumber,
-            Heading: options.verbose
-                ? anchor.headingText
-                : anchor.headingText.substring(0, 60) +
-                    (anchor.headingText.length > 60 ? "..." : ""),
-        }));
-        // Print table
-        console.table(tableData);
-        if (options.verbose) {
-            console.log("\nAnchor Details:");
-            anchors.forEach((anchor, index) => {
-                console.log(`\n${index + 1}. ${anchor.anchor}`);
-                console.log(`   Level: ${anchor.level}`);
-                console.log(`   Line: ${anchor.lineNumber}`);
-                console.log(`   Heading: ${anchor.headingText}`);
-            });
-        }
-        console.log(`\nTotal: ${anchors.length} anchor(s)\n`);
-    }
-    return 0;
-}
-if (require.main === module) {
-    void (0, cli_runtime_1.runCliMain)(main, { errorPrefix: "spec-parse failed" });
-}