@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/add.js

@@ -5,79 +5,69 @@
  * Core add-item operation
  * Creates metadata JSON, description Markdown, and updates distributed index.
  */
-import { existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { generateItemId, getCurrentTimestamp, getTypePrefix, normalizeMarkdown, TYPE_TO_DIRECTORY, } from '../utils/index.js';
+import { existsSync } from 'node:fs';
+import { writeFileAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
+import { addItemWarnings, prepareAddItem, renderAddContent } from './add-preparation.js';
+import { currentLeafReceipt } from './classification-leaf.js';
+import { loadClassificationRegistry } from './classification-registry.js';
 import { getConfig } from './config.js';
-import { addItemToIndex, loadCounters, updateCounters } from './index-refs.js';
-/**
- * Core business logic for adding a new item to devsteps
- * Pure function that handles all file I/O and validation
- */
-export async function addItem(devstepsDir, args) {
-    // Check if initialized
+import { ItemReservationError, reserveItemFolders } from './counters.js';
+import { invalidateItem } from './item-store.js';
+export { docAddHint, validateProcessDefinitionShape } from './add-preparation.js';
+/** Create one item using the same preparation and templates as batch creation. */
+export async function addItem(devstepsDir, args, options = {}) {
     if (!existsSync(devstepsDir)) {
         throw new Error('Project not initialized. Run devsteps-init first.');
     }
-    // Read config and index
     const config = await getConfig(devstepsDir);
-    // Get counter (auto-migration ensures refs-style index is always available)
-    const counterKey = getTypePrefix(args.type); // Use uppercase prefix for consistency
-    const counters = loadCounters(devstepsDir);
-    const counter = (counters[counterKey] || 0) + 1;
-    // Generate ID using global counter
-    const typeFolder = TYPE_TO_DIRECTORY[args.type];
-    const itemId = generateItemId(args.type, counter);
-    // Create metadata
-    const now = getCurrentTimestamp();
-    const metadata = {
-        id: itemId,
-        type: args.type,
-        category: args.category || 'general',
-        title: args.title,
-        status: 'draft',
-        eisenhower: args.eisenhower || 'not-urgent-important',
-        created: now,
-        updated: now,
-        author: args.assignee || config.settings.default_author,
-        assignee: args.assignee,
-        affected_paths: args.affected_paths || [],
-        linked_items: {
-            implements: [],
-            'implemented-by': [],
-            'tested-by': [],
-            tests: [],
-            blocks: [],
-            'blocked-by': [],
-            'relates-to': [],
-            'depends-on': [],
-            'required-by': [],
-            supersedes: [],
-            'superseded-by': [],
-        },
-        tags: args.tags || [],
-        commits: [],
-        metadata: {},
-    };
-    // Save metadata
-    const itemDir = join(devstepsDir, typeFolder);
-    const metadataPath = join(itemDir, `${itemId}.json`);
-    const descriptionPath = join(itemDir, `${itemId}.md`);
-    writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
-    // Save description — normalizeMarkdown converts literal \n sequences from MCP clients
-    // to real newlines (BUG-056: GitHub Copilot ≥ v1.0.0 sends escape sequences, not real newlines)
-    const description = normalizeMarkdown(args.description || `# ${args.title}\n\n<!-- Add detailed description here -->\n`);
-    writeFileSync(descriptionPath, description);
-    // Update index (auto-migration ensures refs-style always available)
-    const currentCounters = loadCounters(devstepsDir);
-    currentCounters[counterKey] = counter;
-    updateCounters(devstepsDir, currentCounters);
-    // Add to all relevant indexes (by-type, by-status, by-priority)
-    addItemToIndex(devstepsDir, metadata);
+    const prepared = await prepareAddItem(devstepsDir, args, config);
+    const { gate, diagnostics } = prepared;
+    const reservation = reserveItemFolders(devstepsDir, [{ key: 'item', type: args.type }]);
+    const claim = reservation.claims.get('item');
+    if (!claim)
+        throw new Error('Single-item reservation returned no claim');
+    const { itemId } = claim;
+    const countersRaised = reservation.countersRaised;
+    const metadata = { id: itemId, ...prepared.metadata };
+    let content;
+    let publicationPhase = 'metadata';
+    try {
+        // Preserve metadata-before-description publication, after confirmed reservation.
+        writeJsonAtomic(claim.paths.metadata, metadata);
+        publicationPhase = 'description';
+        content = renderAddContent(args, itemId, metadata.created, options);
+        writeFileAtomic(claim.paths.description, content.description);
+    }
+    catch (error) {
+        throw new ItemReservationError(error, {
+            phase: publicationPhase,
+            keyToId: reservation.keyToId,
+            reservedKeys: ['item'],
+            failedKey: 'item',
+            countersPersisted: true,
+        });
+    }
+    const { description, hint } = content;
+    invalidateItem(devstepsDir, itemId);
+    const warnings = [
+        ...reservation.warnings,
+        ...addItemWarnings(devstepsDir, metadata, args, description),
+    ];
+    const classification = gate.leaf
+        ? {
+            ...gate,
+            leaf_receipt: await currentLeafReceipt(devstepsDir, gate.category, loadClassificationRegistry(devstepsDir).digest),
+        }
+        : gate;
     return {
         itemId,
+        classification,
         metadata,
         config,
+        countersRaised,
+        ...(args.process_definition !== undefined || diagnostics.length > 0 ? { diagnostics } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+        ...(hint !== undefined ? { hint } : {}),
     };
 }
 //# sourceMappingURL=add.js.map

package/dist/core/add.js.map

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

package/dist/core/archive.d.ts

@@ -3,14 +3,22 @@
  * Licensed under the Apache License, Version 2.0
  *
  * Core archive and purge operations
- * Moves items to .devsteps/archive/ and updates the distributed index.
+ * Moves items to .devsteps/archive/ and drops them from the item store.
  */
-import type { ItemStatus } from '../schemas/index.js';
+import { type ItemStatus } from '../schemas/index.js';
 export interface ArchiveItemResult {
     itemId: string;
     archivedAt: string;
-    originalStatus: ItemStatus;
+    /** Undefined when the stored status was unreadable — the item is archived either way. */
+    originalStatus?: ItemStatus;
+    /** Populated when the archived item violated the schema; empty otherwise. */
+    schemaIssues: string[];
 }
+/**
+ * IDs of every archived item. An archived item still exists, so a link that
+ * points at it is history, not a broken reference (BUG-173).
+ */
+export declare function listArchivedItemIds(devstepsDir: string): string[];
 /**
  * Core business logic for archiving a single item
  */
@@ -23,6 +31,13 @@ export interface PurgeItemsArgs {
 export interface PurgeItemsResult {
     count: number;
     archivedIds: string[];
+    /** Schema-invalid items that were archived along the way (BUG-115 / STORY-391). */
+    invalidIds: string[];
+    /** Items that could not be archived, with the reason — never silently dropped. */
+    skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
 }
 /**
  * Core business logic for bulk archiving items

package/dist/core/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/core/archive.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,qBAAqB,CAAC;AAKhE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,UAAU,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+CjG;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CA8C3B"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/core/archive.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAY,MAAM,qBAAqB,CAAC;AAWhE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,6EAA6E;IAC7E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAIjE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+BjG;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mFAAmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AA0BD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAsE3B"}

package/dist/core/archive.js

@@ -3,14 +3,23 @@
  * Licensed under the Apache License, Version 2.0
  *
  * Core archive and purge operations
- * Moves items to .devsteps/archive/ and updates the distributed index.
+ * Moves items to .devsteps/archive/ and drops them from the item store.
  */
 import { existsSync, mkdirSync, renameSync } from 'node:fs';
-import { join } from 'node:path';
-import { getCurrentTimestamp, parseItemId, TYPE_TO_DIRECTORY } from '../utils/index.js';
-import { getItem } from './get.js';
-import { removeItemFromIndex } from './index-refs.js';
+import { dirname } from 'node:path';
+import { ItemType } from '../schemas/index.js';
+import { getCurrentTimestamp } from '../utils/index.js';
+import { readItemMetadataLenient } from './get.js';
+import { archivedItemPaths, archivedTypeDirectory, itemPaths, listItemFolders, } from './item-paths.js';
+import { invalidateItem, listItemIds } from './item-store.js';
 import { listItems } from './list.js';
+/**
+ * IDs of every archived item. An archived item still exists, so a link that
+ * points at it is history, not a broken reference (BUG-173).
+ */
+export function listArchivedItemIds(devstepsDir) {
+    return ItemType.options.flatMap((type) => listItemFolders(archivedTypeDirectory(devstepsDir, type), type));
+}
 /**
  * Core business logic for archiving a single item
  */
@@ -18,40 +27,49 @@ export async function archiveItem(devstepsDir, itemId) {
     if (!existsSync(devstepsDir)) {
         throw new Error('Project not initialized. Run devsteps-init first.');
     }
-    const parsed = parseItemId(itemId);
-    if (!parsed) {
-        throw new Error(`Invalid item ID: ${itemId}`);
-    }
-    const typeFolder = TYPE_TO_DIRECTORY[parsed.type];
-    const metadataPath = join(devstepsDir, typeFolder, `${itemId}.json`);
-    const descriptionPath = join(devstepsDir, typeFolder, `${itemId}.md`);
-    if (!existsSync(metadataPath)) {
+    const paths = itemPaths(devstepsDir, itemId);
+    if (!existsSync(paths.metadata)) {
         throw new Error(`Item not found: ${itemId}`);
     }
-    // Read metadata
-    const { metadata } = await getItem(devstepsDir, itemId);
+    // BUG-115 / STORY-391: read leniently. Archiving needs the type, the status and
+    // the tags — not a fully valid object. Going through `getItem()` here meant that
+    // an item which violated the schema could never be removed through the API.
+    const metadata = readItemMetadataLenient(devstepsDir, itemId);
     const originalStatus = metadata.status;
-    // Create archive directory if not exists
-    const archiveDir = join(devstepsDir, 'archive', typeFolder);
-    mkdirSync(archiveDir, { recursive: true });
-    // Move files to archive
-    const archiveMetadataPath = join(archiveDir, `${itemId}.json`);
-    const archiveDescriptionPath = join(archiveDir, `${itemId}.md`);
-    renameSync(metadataPath, archiveMetadataPath);
-    if (existsSync(descriptionPath)) {
-        renameSync(descriptionPath, archiveDescriptionPath);
-    }
-    // Update index (auto-migration ensures refs-style always available)
-    // Remove from all indexes (by-type, by-status, by-priority)
-    removeItemFromIndex(devstepsDir, itemId, metadata.type, metadata.status, metadata.eisenhower);
-    // Note: refs-style doesn't track archived_items in index
-    // Archive metadata already contains all needed info
+    // Move the whole folder — master document, metadata and attachments (STORY-427)
+    const archived = archivedItemPaths(devstepsDir, itemId);
+    mkdirSync(dirname(archived.dir), { recursive: true });
+    renameSync(paths.dir, archived.dir);
+    // The item store discovers items from their directories, so moving the files is
+    // the whole removal — just drop the entry the store may still hold (STORY-426).
+    invalidateItem(devstepsDir, itemId);
     return {
         itemId,
         archivedAt: getCurrentTimestamp(),
         originalStatus,
+        schemaIssues: metadata.schemaIssues,
     };
 }
+/**
+ * Item IDs on disk that `listItems()` cannot see because they fail the schema.
+ * Without this scan, purge inherits the blindness of the list path and a broken
+ * item stays in the project forever.
+ */
+function scanSchemaInvalidItems(devstepsDir) {
+    const found = [];
+    for (const id of listItemIds(devstepsDir)) {
+        try {
+            const metadata = readItemMetadataLenient(devstepsDir, id);
+            if (metadata.schemaIssues.length > 0) {
+                found.push({ id, status: metadata.status });
+            }
+        }
+        catch (error) {
+            found.push({ id, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return found;
+}
 /**
  * Core business logic for bulk archiving items
  */
@@ -80,21 +98,48 @@ export async function purgeItems(devstepsDir, args = {}) {
     const itemsToArchive = args.olderThan != null
         ? candidates.filter((i) => new Date(i.updated) < args.olderThan)
         : candidates;
+    // Schema-invalid items never reach listItems(), so collect them separately and
+    // apply the same status filter to whatever status is still readable.
+    const invalidCandidates = [];
+    const skipped = [];
+    for (const invalid of scanSchemaInvalidItems(devstepsDir)) {
+        if (seen.has(invalid.id))
+            continue;
+        if (invalid.reason !== undefined) {
+            skipped.push({ id: invalid.id, reason: invalid.reason });
+        }
+        else if (invalid.status !== undefined && statusFilter.includes(invalid.status)) {
+            seen.add(invalid.id);
+            invalidCandidates.push(invalid.id);
+        }
+        else {
+            skipped.push({
+                id: invalid.id,
+                reason: 'schema-invalid item outside the requested status filter — archive it by ID',
+            });
+        }
+    }
     // Archive each item
     const archivedIds = [];
-    for (const item of itemsToArchive) {
+    const invalidIds = [];
+    for (const id of [...itemsToArchive.map((item) => item.id), ...invalidCandidates]) {
         try {
-            await archiveItem(devstepsDir, item.id);
-            archivedIds.push(item.id);
+            const result = await archiveItem(devstepsDir, id);
+            archivedIds.push(id);
+            if (result.schemaIssues.length > 0)
+                invalidIds.push(id);
         }
         catch (error) {
-            // Continue with next item on error
-            console.error(`Failed to archive ${item.id}:`, error);
+            const reason = error instanceof Error ? error.message : String(error);
+            console.error(`Failed to archive ${id}:`, error);
+            skipped.push({ id, reason });
         }
     }
     return {
         count: archivedIds.length,
         archivedIds,
+        invalidIds,
+        skipped,
     };
 }
 //# sourceMappingURL=archive.js.map

package/dist/core/archive.js.map

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

package/dist/core/auto-migrate-detect.d.ts

@@ -8,46 +8,81 @@
  * These functions only read state and return status information.
  *
  * @see STORY-073 External Project Migration Auto-Detection
+ * @see STORY-426 The item files are the index — tracked index files are removed
+ * @see STORY-427 Every item is a folder
  */
+/** Derived index directories that 2.0 no longer keeps under `.devsteps/index/`. */
+export declare const TRACKED_INDEX_DIRS: readonly ['by-type', 'by-status', 'by-priority', 'by-tag'];
 /**
  * Migration check result
  */
 export interface MigrationCheckResult {
-    /** Whether migration is needed */
+    /** Whether a migration step would change the project. */
     needed: boolean;
-    /** Whether legacy index exists */
-    hasLegacy: boolean;
-    /** Whether refs-style index exists */
-    hasRefs: boolean;
-    /** Number of items in legacy index (if exists) */
+    /** A pre-refs `index.json` still lies in `.devsteps/`. */
+    hasLegacyIndex: boolean;
+    /** A tracked `index/by-*` directory or an `index.backup-*` directory exists. */
+    hasTrackedIndex: boolean;
+    /** `index/counters.json` exists. */
+    hasCounters: boolean;
+    /** Items whose files still lie directly in a type directory, live or archived. */
+    flatItemCount: number;
+    /** Items the legacy index lists, when it is readable. */
     itemCount?: number;
     /** Human-readable status message */
     message: string;
 }
+/** One step of progress through a migration, for a progress bar or a log line. */
+export interface MigrationProgress {
+    step: 'item-folders';
+    done: number;
+    total: number;
+    /** The item just handled. */
+    id: string;
+}
 /**
  * Auto-migration options
  */
 export interface AutoMigrationOptions {
-    /** Skip backup creation (advanced users only) */
-    skipBackup?: boolean;
     /** Silent mode - suppress console output */
     silent?: boolean;
     /** Dry-run mode - check only, don't migrate */
     dryRun?: boolean;
+    /** Called once per item moved into its folder. */
+    onProgress?: (progress: MigrationProgress) => void;
 }
 /**
- * Migration statistics
+ * What the index-removal step did.
  */
 export interface MigrationStats {
-    totalItems: number;
-    byType: Record<string, number>;
-    byStatus: Record<string, number>;
-    byPriority: Record<string, number>;
-    backupPath?: string;
-    archivePath?: string;
+    /** Paths removed, relative to `.devsteps/`. */
+    removed: string[];
+    /** Counters after the step. */
+    counters: Record<string, number>;
+    /** True when counters were missing or below an ID on disk and had to be written. */
+    countersWritten: boolean;
+    warnings?: string[];
+}
+/** An item still in the flat layout: `<typeDir>/<ID>.json` and `<typeDir>/<ID>.md`. */
+export interface FlatItem {
+    typeDir: string;
+    id: string;
 }
+/** Tracked index paths present in the project, relative to `.devsteps/`. */
+export declare function listTrackedIndexPaths(devstepsDir: string): string[];
+/** Items of every type still in the flat layout, live ones first, then archived ones. */
+export declare function listFlatItems(devstepsDir: string): FlatItem[];
+/** Whether the item-folder step has anything to do. */
+export declare function needsItemFolderMigration(devstepsDir: string): boolean;
+/**
+ * Check if legacy index.json exists (migration detection)
+ */
+export declare function hasLegacyIndex(devstepsDir: string): boolean;
+/** Whether the index-removal step has anything to do. */
+export declare function needsIndexRemoval(devstepsDir: string): boolean;
 /**
- * Check if index migration is needed (legacy → refs-style)
+ * Check whether the project still carries a layout the 2.0 artifacts have replaced:
+ * flat item files, tracked index files, or a legacy `index.json`.
  */
 export declare function checkMigrationNeeded(devstepsDir: string): MigrationCheckResult;
 /**

package/dist/core/auto-migrate-detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-migrate-detect.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,CA6B9E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAOzE"}
+{"version":3,"file":"auto-migrate-detect.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,YAAI,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,CAAU,CAAC;AAE7F;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,eAAe,EAAE,OAAO,CAAC;IACzB,oCAAoC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oFAAoF;IACpF,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,uFAAuF;AACvF,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBnE;AAoBD,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,EAAE,CAM7D;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9D;AA0BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAqC9E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CASrE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAOzE"}