cc-agentic-framework 1.14.1

package/dist/lib/link-transformer.js

@@ -0,0 +1,349 @@
+/**
+ * Link Transformer Module
+ *
+ * Transforms relative markdown links to absolute paths when syncing agents/skills
+ * to deployment folders. This ensures links remain valid regardless of where the
+ * deployed files are accessed from.
+ *
+ * Usage:
+ *     const transformer = new LinkTransformer("/path/to/framework");
+ *     const transformedContent = await transformer.transformFile(sourcePath, targetPath);
+ *
+ * Link Type Handling:
+ *     - {project} placeholders
+ *       → Replace with actual project root path
+ *     - Framework files (.claude/registries/*.json, .claude/context/*.md, etc.)
+ *       → Transform to absolute path using framework root
+ *     - Internal files (./EXAMPLES.md, ./STANDARDS.md)
+ *       → Preserve as-is (same directory)
+ *     - External URLs (http://, https://)
+ *       → Preserve as-is
+ *     - Anchor-only links (#section)
+ *       → Preserve as-is
+ *     - Images (.png, .jpg, .gif, .svg, .webp)
+ *       → Preserve as-is
+ *     - Combined links (file.md#section)
+ *       → Transform path, preserve anchor, rejoin
+ */
+import path from 'path';
+import fs from 'fs-extra';
+/**
+ * Transforms markdown links from relative to absolute paths.
+ *
+ * This class handles the transformation of relative markdown links to absolute
+ * paths based on a framework root directory. It intelligently preserves certain
+ * link types (internal files, URLs, anchors, images) while transforming
+ * framework file references.
+ */
+export class LinkTransformer {
+    /** Placeholder for project root in source files - replaced during sync */
+    static PROJECT_PLACEHOLDER = '{project}';
+    /** Framework file patterns that should be transformed to absolute paths */
+    static FRAMEWORK_FILE_PATTERNS = [
+        '.claude/registries/',
+        '.claude/context/',
+        '.claude/framework/',
+        '.claude/commands/',
+        '.claude/skills/',
+        'README.md',
+        'CLAUDE.md',
+        'routes.yml',
+        'backlog/',
+        'confluence/',
+        '.claude/plans/',
+    ];
+    /** Image file extensions to preserve as-is */
+    static IMAGE_EXTENSIONS = new Set([
+        '.png',
+        '.jpg',
+        '.jpeg',
+        '.gif',
+        '.svg',
+        '.webp',
+    ]);
+    /** Markdown link pattern: [text](path) or [text](path#anchor) */
+    static LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/g;
+    frameworkRoot;
+    projectRoot;
+    /**
+     * Initialize the LinkTransformer.
+     *
+     * @param frameworkRoot - Absolute path to the framework source directory (where modules are)
+     * @param projectRoot - Absolute path to the project root (where deployed files go).
+     *                      If not provided, defaults to frameworkRoot for backward compatibility.
+     * @throws {Error} If framework_root is empty, doesn't exist, or is not a directory
+     */
+    constructor(frameworkRoot, projectRoot) {
+        if (!frameworkRoot) {
+            throw new Error('frameworkRoot cannot be empty');
+        }
+        this.frameworkRoot = path.resolve(frameworkRoot);
+        // projectRoot is where {project}/ placeholders should resolve to
+        this.projectRoot = projectRoot ? path.resolve(projectRoot) : this.frameworkRoot;
+        if (!fs.pathExistsSync(this.frameworkRoot)) {
+            throw new Error(`frameworkRoot does not exist: ${this.frameworkRoot}`);
+        }
+        if (!fs.statSync(this.frameworkRoot).isDirectory()) {
+            throw new Error(`frameworkRoot is not a directory: ${this.frameworkRoot}`);
+        }
+    }
+    /**
+     * Transform all links in a markdown file.
+     *
+     * Reads the source file, transforms all markdown links according to the
+     * transformation rules, and returns the transformed content.
+     *
+     * @param sourcePath - Path to the source markdown file
+     * @param targetPath - Path where the file will be deployed (used for context)
+     * @returns Transformed markdown content with absolute links where appropriate
+     * @throws {Error} If source_path does not exist or is not a file
+     */
+    async transformFile(sourcePath, _targetPath) {
+        const resolvedSourcePath = path.resolve(sourcePath);
+        if (!(await fs.pathExists(resolvedSourcePath))) {
+            throw new Error(`Source file not found: ${resolvedSourcePath}`);
+        }
+        const stats = await fs.stat(resolvedSourcePath);
+        if (!stats.isFile()) {
+            throw new Error(`Source path is not a file: ${resolvedSourcePath}`);
+        }
+        // Read source content
+        const content = await fs.readFile(resolvedSourcePath, 'utf-8');
+        // Transform all links
+        return this.transformContent(content, resolvedSourcePath);
+    }
+    /**
+     * Transform content string directly (useful for testing).
+     *
+     * @param content - Markdown content to transform
+     * @param sourcePath - Path to the source file (for resolving relative links)
+     * @returns Transformed markdown content
+     */
+    transformContent(content, sourcePath) {
+        const resolvedSourcePath = path.resolve(sourcePath);
+        // First, replace {project} placeholders with actual project root
+        let transformedContent = this.replaceProjectPlaceholders(content);
+        // Then, replace all relative links in content
+        transformedContent = transformedContent.replace(LinkTransformer.LINK_PATTERN, (match, linkText, linkPath) => {
+            // Transform the link path
+            const transformedPath = this.transformLink(linkPath, resolvedSourcePath);
+            // Return the transformed markdown link
+            return `[${linkText}](${transformedPath})`;
+        });
+        return transformedContent;
+    }
+    /**
+     * Replace {project} placeholders with actual project root path.
+     *
+     * This allows source files to use portable placeholders like:
+     *   [agents.json]({project}/.claude/registries/agents.json)
+     *
+     * Which get transformed to actual paths during sync:
+     *   [agents.json](/path/to/project/.claude/registries/agents.json)
+     *
+     * @param content - Content with potential {project} placeholders
+     * @returns Content with placeholders replaced by actual project root
+     */
+    replaceProjectPlaceholders(content) {
+        // Replace all occurrences of {project} with the project root (deployment target)
+        return content.replace(new RegExp(LinkTransformer.PROJECT_PLACEHOLDER.replace(/[{}]/g, '\\$&'), 'g'), this.projectRoot);
+    }
+    /**
+     * Transform a single link path.
+     *
+     * Determines the link type and applies the appropriate transformation:
+     * - External URLs: preserved as-is
+     * - Anchor-only: preserved as-is
+     * - Images: preserved as-is
+     * - Internal files (./...): preserved as-is
+     * - Placeholder paths (url, path, file, etc.): preserved as-is
+     * - Framework files: transformed to absolute paths
+     *
+     * @param linkPath - The link path to transform
+     * @param sourceFile - The source file containing the link
+     * @returns Transformed link path
+     */
+    transformLink(linkPath, sourceFile) {
+        // Empty link - preserve as-is
+        if (!linkPath || !linkPath.trim()) {
+            return linkPath;
+        }
+        // External URL - preserve as-is
+        if (this.isExternalUrl(linkPath)) {
+            return linkPath;
+        }
+        // Anchor-only link - preserve as-is
+        if (linkPath.startsWith('#')) {
+            return linkPath;
+        }
+        // Image link - preserve as-is
+        if (this.isImageLink(linkPath)) {
+            return linkPath;
+        }
+        // Internal file (starts with ./) - preserve as-is
+        if (this.isInternalFile(linkPath)) {
+            return linkPath;
+        }
+        // Placeholder path - preserve as-is
+        if (this.isPlaceholderPath(linkPath)) {
+            return linkPath;
+        }
+        // Handle combined links (file.md#section)
+        let anchor = null;
+        let pathWithoutAnchor = linkPath;
+        if (linkPath.includes('#')) {
+            const parts = linkPath.split('#');
+            pathWithoutAnchor = parts[0];
+            anchor = parts.slice(1).join('#');
+        }
+        // Resolve the relative path to an absolute path
+        const sourceDir = path.dirname(sourceFile);
+        const resolvedPath = this.resolveRelativePath(pathWithoutAnchor, sourceDir);
+        // Check if this is a framework file
+        if (this.isFrameworkFile(resolvedPath)) {
+            try {
+                // Get path relative to framework root
+                const relativePath = path.relative(this.frameworkRoot, resolvedPath);
+                // Check if path is actually under framework root
+                if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
+                    // Build absolute path
+                    const absolutePath = path.join(this.frameworkRoot, relativePath);
+                    // Add anchor back if it existed
+                    if (anchor) {
+                        return `${absolutePath}#${anchor}`;
+                    }
+                    return absolutePath;
+                }
+                // Path is not under framework root - preserve original
+                if (anchor) {
+                    return `${pathWithoutAnchor}#${anchor}`;
+                }
+                return pathWithoutAnchor;
+            }
+            catch (_error) {
+                // Error computing relative path - preserve original
+                if (anchor) {
+                    return `${pathWithoutAnchor}#${anchor}`;
+                }
+                return pathWithoutAnchor;
+            }
+        }
+        // Not a framework file - preserve original
+        if (anchor) {
+            return `${pathWithoutAnchor}#${anchor}`;
+        }
+        return pathWithoutAnchor;
+    }
+    /**
+     * Check if a resolved path is a framework file that should be transformed.
+     *
+     * Framework files include:
+     * - .claude/registries/*.json
+     * - .claude/context/**\/*.md
+     * - .claude/framework/**\/*.md
+     * - .claude/commands/**\/*.md
+     * - .claude/skills/**\/*.md
+     * - .claude/plans/**\/*.md
+     * - README.md, CLAUDE.md, routes.yml
+     * - backlog/**\/*.md
+     * - confluence/**\/*.md
+     *
+     * @param resolvedPath - Absolute path to check
+     * @returns True if this is a framework file, False otherwise
+     */
+    isFrameworkFile(resolvedPath) {
+        try {
+            // Get path relative to framework root
+            const relativePath = path.relative(this.frameworkRoot, resolvedPath);
+            // If path is outside framework root, it's not a framework file
+            if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+                return false;
+            }
+            // Normalize to forward slashes for consistent matching
+            const normalizedPath = relativePath.split(path.sep).join('/');
+            // Check against framework file patterns
+            for (const pattern of LinkTransformer.FRAMEWORK_FILE_PATTERNS) {
+                if (normalizedPath === pattern || normalizedPath.startsWith(pattern)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        catch (_error) {
+            // Path is not under framework root
+            return false;
+        }
+    }
+    /**
+     * Check if a link is an internal file (starts with ./).
+     *
+     * Internal files are in the same directory as the source file and should
+     * be preserved as-is.
+     *
+     * @param linkPath - Link path to check
+     * @returns True if this is an internal file link, False otherwise
+     */
+    isInternalFile(linkPath) {
+        return linkPath.startsWith('./');
+    }
+    /**
+     * Check if a link is a placeholder path used in documentation examples.
+     *
+     * Placeholder paths are generic examples like 'url', 'path', 'file', etc.
+     * that appear in markdown syntax examples and should be preserved as-is.
+     *
+     * @param linkPath - Link path to check
+     * @returns True if this is a placeholder path, False otherwise
+     */
+    isPlaceholderPath(linkPath) {
+        // Common placeholder values used in documentation
+        const placeholders = new Set(['url', 'path', 'file', 'link', 'href', 'src', 'target']);
+        return placeholders.has(linkPath.toLowerCase().trim());
+    }
+    /**
+     * Check if a link is an external URL.
+     *
+     * External URLs start with http:// or https:// and should be preserved as-is.
+     *
+     * @param linkPath - Link path to check
+     * @returns True if this is an external URL, False otherwise
+     */
+    isExternalUrl(linkPath) {
+        return linkPath.startsWith('http://') || linkPath.startsWith('https://');
+    }
+    /**
+     * Check if a link is an image file.
+     *
+     * Image files have extensions like .png, .jpg, .gif, etc. and should be
+     * preserved as-is.
+     *
+     * @param linkPath - Link path to check
+     * @returns True if this is an image link, False otherwise
+     */
+    isImageLink(linkPath) {
+        // Extract path without anchor
+        const pathOnly = linkPath.split('#')[0];
+        const ext = path.extname(pathOnly).toLowerCase();
+        return LinkTransformer.IMAGE_EXTENSIONS.has(ext);
+    }
+    /**
+     * Resolve a relative path to an absolute path.
+     *
+     * Handles relative paths like:
+     * - ../registry.yml
+     * - ../context/business-advanced.md
+     * - ../../README.md
+     *
+     * @param linkPath - Relative link path
+     * @param fromDir - Directory containing the source file
+     * @returns Resolved absolute path
+     */
+    resolveRelativePath(linkPath, fromDir) {
+        // Combine the source directory with the relative link path
+        const combinedPath = path.join(fromDir, linkPath);
+        // Resolve to absolute path (handles .. and . components)
+        const resolvedPath = path.resolve(combinedPath);
+        return resolvedPath;
+    }
+}
+//# sourceMappingURL=link-transformer.js.map

package/dist/lib/link-transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-transformer.js","sourceRoot":"","sources":["../../src/lib/link-transformer.ts"],"names":[],"mappings":"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"}

package/dist/lib/link-validator.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Markdown Link Validator
+ *
+ * Validates markdown links and detects anti-patterns in framework documentation files.
+ * TypeScript implementation of Python link_validator.py algorithm.
+ *
+ * Features:
+ * - Detects broken file links
+ * - Identifies anti-patterns (backticked paths, unlinked references, plain paths)
+ * - Two-tier strictness (framework files vs content files)
+ * - Comprehensive path resolution (relative, absolute, project-relative)
+ *
+ * @module link-validator
+ */
+/**
+ * Represents a markdown link found in a file
+ */
+export interface MarkdownLink {
+    /** Link text (the part in square brackets) */
+    text: string;
+    /** Link target path or URL */
+    target: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column start position */
+    columnStart: number;
+    /** Column end position */
+    columnEnd: number;
+}
+/**
+ * Represents a broken or invalid link
+ */
+export interface BrokenLink {
+    /** Source file containing the broken link */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Link text */
+    linkText: string;
+    /** Target path that was broken */
+    target: string;
+    /** Reason why the link is broken */
+    reason: string;
+    /** Resolved absolute path (for debugging) */
+    resolvedPath?: string;
+}
+/**
+ * Represents a documentation anti-pattern
+ */
+export interface AntiPattern {
+    /** Source file containing the anti-pattern */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Type of anti-pattern detected */
+    patternType: "backticked_path" | "unlinked_reference" | "plain_path_in_workflow";
+    /** Pattern content */
+    pattern: string;
+    /** Suggested fix */
+    suggestion: string;
+}
+/**
+ * Validation results for markdown links
+ */
+export interface LinkValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** List of broken links found */
+    brokenLinks: BrokenLink[];
+    /** List of anti-patterns detected */
+    antiPatterns: AntiPattern[];
+    /** Number of files checked */
+    filesChecked: number;
+    /** Number of links checked */
+    linksChecked: number;
+}
+/**
+ * File-specific validation result
+ */
+interface FileValidationResult {
+    file: string;
+    isFrameworkFile: boolean;
+    valid: boolean;
+    brokenLinks: BrokenLink[];
+    antiPatterns: AntiPattern[];
+    linksChecked: number;
+}
+/**
+ * Markdown Link Validator
+ *
+ * Validates markdown links in framework documentation with two-tier strictness:
+ * - Framework core files (.claude/, src/, core/, cli/) → critical errors
+ * - Content files (backlog/, docs/) → warnings only
+ *
+ * @example
+ * ```typescript
+ * const validator = new MarkdownLinkValidator('/path/to/framework');
+ * const result = await validator.validateFile('.claude/commands/architect.md');
+ * if (!result.valid) {
+ *   console.log(`Found ${result.brokenLinks.length} broken links`);
+ * }
+ * ```
+ */
+export declare class MarkdownLinkValidator {
+    /** Framework root directory */
+    private readonly frameworkRoot;
+    /** Framework core paths (critical) */
+    private static readonly FRAMEWORK_CORE_PATHS;
+    /** Framework root files (critical) */
+    private static readonly FRAMEWORK_ROOT_FILES;
+    /** Content paths (non-critical warnings) */
+    private static readonly CONTENT_PATHS;
+    /** Markdown link regex: [text](path) */
+    private static readonly LINK_PATTERN;
+    /** Backticked path regex */
+    private static readonly BACKTICK_PATTERN;
+    /** Unlinked "See:" reference regex */
+    private static readonly SEE_PATTERN;
+    /** Plain path in workflow regex */
+    private static readonly WORKFLOW_PATTERN;
+    /** Image file extensions to skip */
+    private static readonly IMAGE_EXTENSIONS;
+    /** Placeholder paths to skip */
+    private static readonly PLACEHOLDERS;
+    /** Example link text patterns that indicate documentation examples */
+    private static readonly EXAMPLE_LINK_TEXTS;
+    /** Template patterns to exclude from anti-pattern detection */
+    private static readonly TEMPLATE_PATTERNS;
+    /**
+     * Create a new MarkdownLinkValidator
+     *
+     * @param frameworkRoot - Absolute path to framework root directory
+     */
+    constructor(frameworkRoot: string);
+    /**
+     * Validate markdown links in a single file
+     *
+     * @param filePath - Absolute or relative path to markdown file
+     * @returns File validation result
+     * @throws Error if file cannot be read
+     */
+    validateFile(filePath: string): Promise<FileValidationResult>;
+    /**
+     * Validate markdown links in multiple files
+     *
+     * @param files - Array of file paths to validate
+     * @returns Aggregated validation result
+     */
+    validateMarkdownLinks(files?: string[]): Promise<LinkValidationResult>;
+    /**
+     * Find all markdown links in content
+     *
+     * @param content - Markdown content to scan
+     * @returns Array of detected markdown links
+     */
+    findMarkdownLinks(content: string): MarkdownLink[];
+    /**
+     * Detect anti-patterns in markdown content
+     *
+     * @param content - Markdown content to scan
+     * @param filePath - Path to file (for reporting)
+     * @returns Array of detected anti-patterns
+     */
+    detectAntiPatterns(content: string, filePath: string): AntiPattern[];
+    /**
+     * Check if a path is a template pattern (should not be flagged as anti-pattern)
+     *
+     * @param mdPath - Path to check
+     * @returns True if path matches a template pattern
+     */
+    private isTemplatePattern;
+    /**
+     * Resolve a link path to an absolute path
+     *
+     * Handles:
+     * - Relative paths: ../context/file.md
+     * - Project-relative absolute paths: /.claude/commands/file.md
+     * - Fully-qualified absolute paths: /Users/.../project/.claude/file.md
+     * - Anchor removal: file.md#section → file.md
+     * - URL decoding: my%20docs/file.md → my docs/file.md
+     *
+     * @param linkTarget - Link target path
+     * @param sourceFile - Absolute path to source file
+     * @returns Resolved absolute path
+     */
+    private resolveLinkPath;
+    /**
+     * Check if a file exists
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if file exists
+     */
+    private fileExists;
+    /**
+     * Check if a path is a framework core file (critical)
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if framework core file
+     */
+    isFrameworkFile(filePath: string): boolean;
+    /**
+     * Check if a URL is external (HTTP/HTTPS) or uses another protocol
+     *
+     * @param url - URL to check
+     * @returns True if external URL or protocol link
+     */
+    isExternalUrl(url: string): boolean;
+    /**
+     * Check if a link appears to be a documentation example
+     *
+     * @param linkText - The text of the link
+     * @param target - The link target
+     * @returns True if link appears to be an example
+     */
+    private isExampleLink;
+    /**
+     * Check if a path is an image file
+     *
+     * @param filePath - File path to check
+     * @returns True if image file
+     */
+    private isImageFile;
+    /**
+     * Check if a path is a placeholder
+     *
+     * @param linkPath - Path to check
+     * @returns True if placeholder
+     */
+    isPlaceholder(linkPath: string): boolean;
+}
+export {};
+//# sourceMappingURL=link-validator.d.ts.map

package/dist/lib/link-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-validator.d.ts","sourceRoot":"","sources":["../../src/lib/link-validator.ts"],"names":[],"mappings":"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"}