/**
 * Item Converter
 *
 * Converts external items (GitHub/JIRA/ADO) to SpecWeave living docs User Stories.
 * CRITICAL: Does NOT create increments - only creates living docs.
 *
 * NOTE: This file uses extracted modules from ./item-converter/ for better separation
 * of concerns. The main ItemConverter class remains here for backward compatibility.
 *
 * @since v1.0.115 - Extracted helpers to ./item-converter/ modules
 */
import type { ExternalItem } from './external-importer.js';
import type { ExternalContainerContext } from '../core/types/increment-metadata.js';
import { Logger } from '../utils/logger.js';
import { type HierarchyMappingConfig } from '../core/types/sync-profile.js';
/**
 * Set the logger for this module
 */
export declare function setItemConverterLogger(logger: Logger): void;
export interface ConvertedUserStory {
    /** User Story ID with E suffix (e.g., US-001E) */
    id: string;
    /** User Story title */
    title: string;
    /** User Story description */
    description: string;
    /** Acceptance criteria */
    acceptanceCriteria: string[];
    /** Priority (P0-P4) */
    priority?: string;
    /** Status (open, in-progress, completed) */
    status: string;
    /** External metadata */
    metadata: {
        externalId: string;
        externalUrl: string;
        externalPlatform: 'github' | 'jira' | 'ado';
        importedAt: string;
        createdAt: string;
        updatedAt: string;
        labels: string[];
        sourceRepo?: string;
    };
    /** Living docs file path */
    filePath: string;
    /** Living docs markdown content */
    markdown: string;
    /** Feature ID this user story belongs to (when feature allocation enabled) */
    featureId?: string;
}
export interface ItemConverterOptions {
    /** Base directory for living docs (e.g., .specweave/docs/internal/specs) */
    specsDir: string;
    /** Starting US-ID number for imported items (default: 1) */
    startingId?: number;
    /** Project root for FS-ID allocator and ID registry */
    projectRoot?: string;
    /** Enable feature-level organization with FS-ID allocation */
    enableFeatureAllocation?: boolean;
    /** Project ID for multi-project mode (default: 'default') */
    projectId?: string;
    /**
     * Enable global FS-ID collision detection across ALL projects (umbrella mode)
     *
     * CRITICAL: Set this to true in umbrella/multi-repo setups to prevent ID
     * collisions like FS-001 in project-a and FS-001E in project-b.
     *
     * Default: false (for backwards compatibility)
     */
    enableGlobalCollisionDetection?: boolean;
    /** Enable duplicate detection (default: true) */
    enableDuplicateDetection?: boolean;
    /** Auto-archive items older than this many days (default: 0 = disabled, was 30 before v0.30.5) */
    autoArchiveAfterDays?: number;
    /**
     * Hierarchy mapping for converting external work items to SpecWeave levels
     *
     * Maps external tool work item types (Epic, Feature, User Story, Task, etc.)
     * to SpecWeave hierarchy levels (epic, feature, user_story, task, skip).
     *
     * Default mappings:
     * - ADO: DEFAULT_ADO_HIERARCHY_MAPPING
     * - JIRA: DEFAULT_JIRA_HIERARCHY_MAPPING
     * - GitHub: DEFAULT_GITHUB_HIERARCHY_MAPPING
     */
    hierarchyMapping?: HierarchyMappingConfig;
    /**
     * How to handle orphan items (items without parents in the hierarchy)
     *
     * - 'group': Group all orphans under _orphans/ folder (RECOMMENDED - v0.30.6 default)
     * - 'skip': Don't import orphan items
     * - 'create-feature': Create individual FS-XXXE folders (legacy behavior, causes bug)
     *
     * Default: 'group' (v0.30.6+) - orphans go to _orphans/ folder inside project/board
     *
     * The _orphans folder follows industry-standard naming (git orphan branches,
     * database orphan records) for items without parents in the hierarchy.
     */
    orphanHandling?: 'skip' | 'group' | 'create-feature';
    /** Callback for skipped duplicates */
    onDuplicateSkipped?: (externalId: string, existingUsId: string) => void;
    /** Callback for parent change (file moved due to hierarchy update) */
    onParentChanged?: (usId: string, oldFeatureId: string, newFeatureId: string, reason: string) => void;
    /** Callback for feature folder creation */
    onFeatureCreated?: (featureId: string, featurePath: string) => void;
    /** Callback for archived items */
    onItemArchived?: (usId: string, reason: string) => void;
    /**
     * External container context for 2-level directory structure
     *
     * When provided, creates 2-level structure:
     * - JIRA: specs/{projectKey}/{boardName}/FS-XXX/ (e.g., AAC/aac/)
     * - ADO: specs/{projectName}/{areaPath}/FS-XXX/
     *
     * When NOT provided (default), creates 1-level structure:
     * - GitHub: specs/{projectId}/FS-XXX/
     *
     * CRITICAL (v0.35.2): Removed "JIRA-" prefix to match ADO behavior
     *
     * @example
     * ```typescript
     * // JIRA board-based setup (NO JIRA- prefix!)
     * externalContainer: {
     *   type: 'jira-project',
     *   containerId: 'AAC',  // Raw projectKey (uppercase)
     *   containerName: 'Ancillary Apps - CC',
     *   boardId: 338,
     *   boardName: 'Ancillary Apps - CC board'
     * }
     * // Result: specs/AAC/aac/FS-XXX/
     *
     * // ADO area path setup
     * externalContainer: {
     *   type: 'ado-project',
     *   containerId: 'MyProduct',
     *   containerName: 'My Product',
     *   areaPath: 'MyProduct\\Frontend'
     * }
     * ```
     */
    externalContainer?: ExternalContainerContext;
}
/**
 * Convert external items to living docs User Stories
 *
 * CRITICAL: This function ONLY creates living docs files.
 * It does NOT create increments or populate .specweave/increments/.
 */
export declare class ItemConverter {
    private options;
    private duplicateDetector;
    private fsIdAllocator;
    private epicIdAllocator;
    /** Cache of created feature folders to avoid duplicates */
    private createdFeatures;
    /** Cache of created epic folders to avoid duplicates */
    private createdEpics;
    /** Markdown generator for living docs content */
    private markdownGen;
    constructor(options: ItemConverterOptions);
    /**
     * Get the SpecWeave hierarchy level for a work item type
     *
     * Uses the new array-based HierarchyMappingConfig for flexible mapping.
     * Works with ANY hierarchy depth (3/4/5 levels) and ANY external tool.
     *
     * **Core Principle:**
     * - User Story and Task are FIXED (always the same mapping)
     * - Container levels (Epic/Feature) are FLEXIBLE (configurable per project)
     *
     * @param workItemType - External work item type (e.g., 'Epic', 'User Story', 'Task')
     * @param platform - Platform (ado, jira, github) for default mapping selection
     * @returns SpecWeave hierarchy level (epic, feature, user_story, task, skip)
     */
    private getSpecWeaveLevel;
    /**
     * Get default hierarchy mapping for a platform
     */
    private getDefaultMapping;
    /**
     * Case-insensitive check if a type matches any item in an array
     */
    private typeMatchesArray;
    /**
     * Check if a work item type is a "container-level" type (epic or feature)
     *
     * Container-level types create folders (EP-* or FS-*), not user story files.
     */
    private isFeatureLevelType;
    /**
     * Get user-friendly label for JIRA work item type
     */
    private getJiraWorkItemTypeLabel;
    /**
     * Convert a single external item to a User Story with E suffix
     *
     * @param item - External item to convert
     * @param usId - User Story ID number
     * @param featureId - Optional feature ID for folder organization
     * @param childTasks - Optional array of child Task items (v0.30.3: rendered as checkboxes)
     */
    convertItem(item: ExternalItem, usId: number, featureId?: string, childTasks?: ExternalItem[]): ConvertedUserStory;
    /**
     * Convert multiple external items to User Stories
     *
     * CRITICAL: This method ONLY creates living docs files.
     * It does NOT create increments.
     *
     * CRITICAL FIX (2025-12-04): Now uses collision detection for US-IDs
     * - Scans existing US-XXX and US-XXXE files in the project
     * - Includes _orphans folder in scan
     * - Prevents US-ID collisions between imports
     *
     * CRITICAL FIX (2025-12-05): Prevents empty FS-XXXE folder creation on re-import
     * - Checks if ANY item in group is non-duplicate BEFORE allocating folder
     * - Only creates folder if at least one new item will be converted
     */
    convertItems(items: ExternalItem[]): Promise<ConvertedUserStory[]>;
    /**
     * Group items by feature (based on source repo, parent hierarchy, or labels)
     *
     * CRITICAL FIX (2025-12-02): Intelligent ADO Hierarchy Mapping for SAFe/Enterprise
     *
     * ADO Hierarchy (5-level SAFe): Capability → Epic → Feature → User Story → Task
     *
     * SpecWeave Mapping:
     * - Capability (ADO 5th level) → SpecWeave Epic (_epics/EP-XXXE/)
     * - Epic (ADO 4th level, child of Capability) → SpecWeave Feature (FS-XXXE/) with parent ref
     * - Epic (ADO 4th level, standalone) → SpecWeave Epic (_epics/EP-XXXE/)
     * - Feature (ADO 3rd level) → SpecWeave Feature (FS-XXXE/)
     * - User Story → us-xxxe.md in parent Feature folder
     *
     * Group Key Prefixes:
     * - "epic:" → Item goes to _epics/EP-XXXE/ (Capability or standalone Epic)
     * - "feature:" → Item goes to FS-XXXE/ (Epic under Capability, or Feature)
     * - "orphan:" → Individual FS-XXXE/ folder (no parent)
     * - "missing-parent:" → Grouped by missing parent ID
     */
    private groupItemsByFeature;
    /**
     * Allocate a feature ID for a group of items
     *
     * CRITICAL FIX (2025-12-02): Handle "epic:" groups using EpicIdAllocator
     *
     * Group Key Handling:
     * - "epic:..." → Use EpicIdAllocator, create in _epics/EP-XXXE/
     * - "feature:..." → Use FSIdAllocator, create in FS-XXXE/
     * - "orphan:..." → Use FSIdAllocator, create in FS-XXXE/
     * - Other → Use FSIdAllocator
     *
     * CRITICAL (v0.30.3): This method ALWAYS returns a FEATURE ID (FS-XXXE).
     * For epic groups, it creates the epic in {project}/_epics/ AND a feature folder.
     * User stories are NEVER placed in epic folders directly.
     *
     * @returns Feature ID (FS-XXXE) - NEVER returns Epic ID
     */
    private allocateFeatureForGroup;
    /**
     * Check if ALL items in a group should be archived
     */
    private shouldArchiveEntireGroup;
    /**
     * Get base directory for specs, handling both 1-level and 2-level structures
     *
     * Structure patterns:
     * - 2-level (JIRA): specs/{projectKey}/{boardName}/ (e.g., AAC/aac/)
     * - 2-level (ADO): specs/{projectName}/{areaPath}/
     * - 1-level (GitHub): specs/{projectId}/
     * - Legacy: specs/ (no projectId)
     *
     * CRITICAL (v0.35.2): JIRA no longer uses "JIRA-" prefix to match ADO behavior
     *
     * IMPORTANT: For 2-level structure, features ALWAYS go in the inner folder (board/area level),
     * even when containerDirName == projectId (e.g., specs/my-project/my-project/).
     * This is correct because the outer folder is PROJECT level, inner is BOARD level.
     */
    private getBaseDirectory;
    /**
     * Create feature folder with FEATURE.md
     *
     * CRITICAL FIX (2025-12-02): Support parent Epic reference for ADO Epic→Feature mapping
     *
     * @param featureId - Feature ID (e.g., "FS-001E")
     * @param firstItem - First item in the group (used for metadata)
     * @param groupKey - Group key for caching
     * @param shouldArchive - If true, create feature folder in _archive/ directory
     * @param parentEpicId - Optional parent Epic ID (EP-XXXE) for hierarchy reference
     */
    private createFeatureFolder;
    /**
     * Check if an item should be auto-archived based on creation date
     */
    private shouldAutoArchive;
    /**
     * Check if parent has changed between existing reference and new item
     *
     * CRITICAL (2025-12-01): Detects orphan → has parent, or parent ID change
     *
     * @param existingRef - Existing reference from living docs
     * @param newItem - New item being imported
     * @returns True if parent has changed and file should be moved
     */
    private hasParentChanged;
    /**
     * Handle parent change by moving file to new feature folder
     *
     * CRITICAL (2025-12-01): Moves US file when hierarchy changes on re-import
     *
     * @param existingRef - Existing reference with old location
     * @param newItem - New item with updated parent info
     * @param newFeatureId - New feature folder ID (if already allocated for group)
     */
    private handleParentChange;
    /**
     * Update parent metadata in file content
     */
    private updateParentMetadataInContent;
    /**
     * Find existing feature folders for item groups by scanning FEATURE.md files
     *
     * CRITICAL FIX (2025-12-05): Prevents duplicate FS-XXXE folder creation on re-import
     *
     * For GitHub items grouped by sourceRepo, this finds any existing FS-XXXE folder
     * that has the same source_repo in its FEATURE.md frontmatter.
     *
     * @param itemGroups - Groups of items from groupItemsByFeature()
     * @returns Map from groupKey to existing feature ID (e.g., "anton-abyzov/specweave" -> "FS-111E")
     */
    private findExistingFeatureFolders;
    /**
     * Check if a group has at least one non-duplicate item
     *
     * CRITICAL FIX (2025-12-05): Prevents empty folder creation when all items are duplicates
     *
     * @param groupItems - Items in a group
     * @returns True if at least one item is NOT a duplicate
     */
    private groupHasNonDuplicates;
    /**
     * Clean up empty feature folder after file move
     *
     * Checks if folder is empty (except FEATURE.md) and removes it if orphan folder
     */
    private cleanupEmptyFeatureFolder;
    /**
     * Validate that no increments were created
     *
     * CRITICAL: This validation ensures we're not auto-creating increments.
     */
    static validateNoIncrementsCreated(projectRoot: string): void;
    /**
     * TESTING ONLY: Expose private method for unit tests
     * DO NOT use in production code
     */
    __test__groupItemsByFeature(items: ExternalItem[]): Map<string, ExternalItem[]>;
}
//# sourceMappingURL=item-converter.d.ts.map