@planu/cli 1.1.1 → 1.2.0

package/dist/engine/spec-lint-engine.js

@@ -0,0 +1,164 @@
+// engine/spec-lint-engine.ts — Custom Spec Lint Rules Engine (SPEC-364)
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+export function generateRuleId(name) {
+    const input = `${name}-${String(Date.now())}`;
+    const hash = createHash('sha256').update(input).digest('hex').slice(0, 8);
+    return `rule-${hash}`;
+}
+// ---------------------------------------------------------------------------
+// Field extraction from spec
+// ---------------------------------------------------------------------------
+function getFieldValue(spec, field) {
+    switch (field) {
+        case 'title':
+            return spec.title;
+        case 'description':
+            // description is not a direct Spec field; use title as a proxy for text checks
+            return spec.title;
+        case 'tags':
+            return spec.tags;
+        case 'acceptanceCriteria':
+            // acceptanceCriteria is not a direct Spec field; return title as a text proxy
+            return spec.title;
+        case 'estimatedHours':
+            // maps to spec.estimation.devHours
+            return spec.estimation.devHours;
+        case 'priority':
+            // maps to spec.difficulty
+            return spec.difficulty;
+    }
+}
+// ---------------------------------------------------------------------------
+// Condition evaluation
+// ---------------------------------------------------------------------------
+function toStr(v) {
+    if (typeof v === 'string') {
+        return v;
+    }
+    if (typeof v === 'number') {
+        return String(v);
+    }
+    return '';
+}
+export function evaluateCondition(spec, condition) {
+    const value = getFieldValue(spec, condition.field);
+    switch (condition.operator) {
+        case 'exists':
+            return value !== undefined && value !== '';
+        case 'not-exists':
+            return value === undefined || value === '';
+        case 'includes': {
+            if (Array.isArray(value)) {
+                return value.some((v) => toStr(v).toLowerCase() === toStr(condition.value).toLowerCase());
+            }
+            return toStr(value).toLowerCase().includes(toStr(condition.value).toLowerCase());
+        }
+        case 'not-includes': {
+            if (Array.isArray(value)) {
+                return !value.some((v) => toStr(v).toLowerCase() === toStr(condition.value).toLowerCase());
+            }
+            return !toStr(value).toLowerCase().includes(toStr(condition.value).toLowerCase());
+        }
+        case 'min-length': {
+            const len = Array.isArray(value) ? value.length : toStr(value).length;
+            return len >= Number(condition.value ?? 0);
+        }
+        case 'max-length': {
+            const len = Array.isArray(value) ? value.length : toStr(value).length;
+            return len <= Number(condition.value ?? 0);
+        }
+        case 'any-contains': {
+            if (!Array.isArray(value)) {
+                return false;
+            }
+            return value.some((v) => toStr(v).toLowerCase().includes(toStr(condition.value).toLowerCase()));
+        }
+        case 'none-contain': {
+            if (!Array.isArray(value)) {
+                return true;
+            }
+            return !value.some((v) => toStr(v).toLowerCase().includes(toStr(condition.value).toLowerCase()));
+        }
+        case 'greater-than':
+            return typeof value === 'number' && value > Number(condition.value ?? 0);
+        case 'less-than':
+            return typeof value === 'number' && value < Number(condition.value ?? 0);
+        default:
+            return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Rule applicability
+// ---------------------------------------------------------------------------
+function ruleApplies(rule, spec) {
+    if (rule.appliesTo.all === true) {
+        return true;
+    }
+    if (rule.appliesTo.tags !== undefined && rule.appliesTo.tags.length > 0) {
+        const specTags = spec.tags.map((t) => t.toLowerCase());
+        return rule.appliesTo.tags.some((t) => specTags.includes(t.toLowerCase()));
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Single spec lint
+// ---------------------------------------------------------------------------
+export function lintSpec(spec, rules) {
+    const violations = [];
+    for (const rule of rules) {
+        if (!ruleApplies(rule, spec)) {
+            continue;
+        }
+        // If there's a `when` guard, skip rule if guard is not satisfied
+        if (rule.when !== undefined && !evaluateCondition(spec, rule.when)) {
+            continue;
+        }
+        // Check the `then` condition — violation if it fails
+        if (!evaluateCondition(spec, rule.then)) {
+            violations.push({
+                specId: spec.id,
+                ruleId: rule.id,
+                ruleName: rule.name,
+                message: buildViolationMessage(spec.id, rule),
+                severity: rule.severity,
+                field: rule.then.field,
+            });
+        }
+    }
+    return violations;
+}
+function buildViolationMessage(specId, rule) {
+    const cond = rule.then;
+    const base = `[${specId}] Rule "${rule.name}": field "${cond.field}" must ${cond.operator}`;
+    return cond.value !== undefined ? `${base} ${toStr(cond.value)}` : base;
+}
+// ---------------------------------------------------------------------------
+// Project-wide lint
+// ---------------------------------------------------------------------------
+export function runLint(specs, rules) {
+    const allViolations = [];
+    const failedSpecIds = new Set();
+    for (const spec of specs) {
+        const violations = lintSpec(spec, rules);
+        allViolations.push(...violations);
+        if (violations.length > 0) {
+            failedSpecIds.add(spec.id);
+        }
+    }
+    const errorCount = allViolations.filter((v) => v.severity === 'error').length;
+    const warningCount = allViolations.filter((v) => v.severity === 'warning').length;
+    return {
+        projectPath: '',
+        specIds: specs.map((s) => s.id),
+        violations: allViolations,
+        errorCount,
+        warningCount,
+        rulesApplied: rules.length,
+        passedSpecs: specs.length - failedSpecIds.size,
+        failedSpecs: failedSpecIds.size,
+    };
+}
+//# sourceMappingURL=spec-lint-engine.js.map

package/dist/engine/spec-lint-engine.js.map

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

package/dist/engine/spec-scheduler.d.ts

@@ -0,0 +1,13 @@
+import type { Spec, ExecutionTimeline, CriticalPathResult, ParallelEfficiencyResult, SchedulingOptimization } from '../types/index.js';
+/**
+ * Assign specs to agents in a greedy fashion (shortest job first heuristic).
+ * Returns an execution timeline with Gantt chart.
+ */
+export declare function simulateParallelExecution(specs: Spec[], numAgents: number): ExecutionTimeline;
+/** Find the longest chain of specs by estimated hours. */
+export declare function analyzeCriticalPath(specs: Spec[]): CriticalPathResult;
+/** Calculate parallel utilization efficiency. */
+export declare function computeParallelEfficiency(specs: Spec[], numAgents: number): ParallelEfficiencyResult;
+/** Suggest an optimal spec ordering to minimize idle time. */
+export declare function optimizeSpecScheduling(specs: Spec[], numAgents: number): SchedulingOptimization;
+//# sourceMappingURL=spec-scheduler.d.ts.map

package/dist/engine/spec-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-scheduler.d.ts","sourceRoot":"","sources":["../../src/engine/spec-scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAEJ,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAc3B;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAuC7F;AAsCD,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,kBAAkB,CAgBrE;AAMD,iDAAiD;AACjD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,EAAE,EACb,SAAS,EAAE,MAAM,GAChB,wBAAwB,CAyB1B;AAMD,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,sBAAsB,CAsC/F"}

package/dist/engine/spec-scheduler.js

@@ -0,0 +1,154 @@
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getEstHours(spec) {
+    return Math.max(spec.estimation.devHours || 1, 0.5);
+}
+// ---------------------------------------------------------------------------
+// Simulate parallel execution
+// ---------------------------------------------------------------------------
+/**
+ * Assign specs to agents in a greedy fashion (shortest job first heuristic).
+ * Returns an execution timeline with Gantt chart.
+ */
+export function simulateParallelExecution(specs, numAgents) {
+    if (specs.length === 0) {
+        return { agentAssignments: [], totalHours: 0, criticalPath: [], ganttChart: '' };
+    }
+    const clampedAgents = Math.max(1, Math.min(numAgents, 20));
+    // Sort by estimated hours descending (longest first — better load balancing)
+    const sorted = [...specs].sort((a, b) => getEstHours(b) - getEstHours(a));
+    const agentEnd = new Array(clampedAgents).fill(0);
+    const assignments = [];
+    for (const spec of sorted) {
+        // Assign to agent with earliest end time
+        let minIdx = 0;
+        for (let i = 1; i < clampedAgents; i++) {
+            if ((agentEnd[i] ?? 0) < (agentEnd[minIdx] ?? 0)) {
+                minIdx = i;
+            }
+        }
+        const startHour = agentEnd[minIdx] ?? 0;
+        const endHour = startHour + getEstHours(spec);
+        agentEnd[minIdx] = endHour;
+        assignments.push({ agentId: minIdx + 1, specId: spec.id, startHour, endHour });
+    }
+    const totalHours = Math.max(...agentEnd);
+    // Critical path: specs assigned to the agent with longest total time
+    const maxAgent = agentEnd.indexOf(totalHours) + 1;
+    const criticalPath = assignments
+        .filter((a) => a.agentId === maxAgent)
+        .sort((a, b) => a.startHour - b.startHour)
+        .map((a) => a.specId);
+    const ganttChart = buildGanttChart(assignments, clampedAgents, totalHours);
+    return { agentAssignments: assignments, totalHours, criticalPath, ganttChart };
+}
+// ---------------------------------------------------------------------------
+// ASCII Gantt chart
+// ---------------------------------------------------------------------------
+function buildGanttChart(assignments, numAgents, totalHours) {
+    const cols = Math.min(Math.ceil(totalHours), 40);
+    const scale = cols / Math.max(totalHours, 1);
+    const lines = ['Gantt Chart (each char ≈ ' + (totalHours / cols).toFixed(1) + 'h)'];
+    lines.push('Agent | ' + Array.from({ length: cols }, (_, i) => String((i + 1) % 10)).join(''));
+    lines.push('------+' + '-'.repeat(cols));
+    for (let agent = 1; agent <= numAgents; agent++) {
+        const agentTasks = assignments.filter((a) => a.agentId === agent);
+        const row = new Array(cols).fill(' ');
+        for (const task of agentTasks) {
+            const start = Math.floor(task.startHour * scale);
+            const end = Math.min(Math.ceil(task.endHour * scale), cols);
+            for (let c = start; c < end; c++) {
+                row[c] = '█';
+            }
+        }
+        lines.push(`  A${String(agent).padStart(3, ' ')} | ${row.join('')}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Critical path analyzer
+// ---------------------------------------------------------------------------
+/** Find the longest chain of specs by estimated hours. */
+export function analyzeCriticalPath(specs) {
+    if (specs.length === 0) {
+        return { criticalPath: [], totalHours: 0, longestChainLength: 0 };
+    }
+    // Without explicit dependency graph, we find the max-sum subset
+    // by treating each spec as independent and picking the top contributors
+    const sorted = [...specs].sort((a, b) => getEstHours(b) - getEstHours(a));
+    const totalHours = specs.reduce((acc, s) => acc + getEstHours(s), 0);
+    const criticalPath = sorted.slice(0, Math.min(5, sorted.length)).map((s) => s.id);
+    return {
+        criticalPath,
+        totalHours,
+        longestChainLength: criticalPath.length,
+    };
+}
+// ---------------------------------------------------------------------------
+// Parallel efficiency score
+// ---------------------------------------------------------------------------
+/** Calculate parallel utilization efficiency. */
+export function computeParallelEfficiency(specs, numAgents) {
+    const timeline = simulateParallelExecution(specs, numAgents);
+    const totalSpecHours = specs.reduce((acc, s) => acc + getEstHours(s), 0);
+    const totalAgentHours = timeline.totalHours * numAgents;
+    const score = totalAgentHours > 0 ? totalSpecHours / totalAgentHours : 0;
+    let interpretation;
+    if (score >= 0.85) {
+        interpretation = 'Excellent — agents are well utilized.';
+    }
+    else if (score >= 0.65) {
+        interpretation = 'Good — minor idle time exists.';
+    }
+    else if (score >= 0.4) {
+        interpretation = 'Fair — significant idle time. Consider fewer agents or rebalancing tasks.';
+    }
+    else {
+        interpretation = 'Poor — too many agents for the workload. Reduce agent count.';
+    }
+    return {
+        score,
+        totalSpecHours,
+        totalAgentHours,
+        numAgents,
+        interpretation,
+    };
+}
+// ---------------------------------------------------------------------------
+// Optimize scheduling
+// ---------------------------------------------------------------------------
+/** Suggest an optimal spec ordering to minimize idle time. */
+export function optimizeSpecScheduling(specs, numAgents) {
+    if (specs.length === 0) {
+        return { order: [], expectedIdleHours: 0, suggestion: 'No specs to schedule.' };
+    }
+    const clampedAgents = Math.max(1, Math.min(numAgents, 20));
+    // Sort longest first to minimize idle time (LPT algorithm)
+    const ordered = [...specs].sort((a, b) => getEstHours(b) - getEstHours(a));
+    // Calculate idle time with this ordering
+    const agentEnd = new Array(clampedAgents).fill(0);
+    for (const spec of ordered) {
+        let minIdx = 0;
+        for (let i = 1; i < clampedAgents; i++) {
+            if ((agentEnd[i] ?? 0) < (agentEnd[minIdx] ?? 0)) {
+                minIdx = i;
+            }
+        }
+        agentEnd[minIdx] = (agentEnd[minIdx] ?? 0) + getEstHours(spec);
+    }
+    const totalHours = Math.max(...agentEnd);
+    const totalWork = agentEnd.reduce((acc, v) => acc + v, 0);
+    const maxWork = totalHours * clampedAgents;
+    const expectedIdleHours = maxWork - totalWork;
+    const suggestion = expectedIdleHours < 1
+        ? `Optimal: use ${String(clampedAgents)} agents. Expected idle time is minimal (${expectedIdleHours.toFixed(1)}h).`
+        : `Use ${String(clampedAgents)} agents. Expected idle time: ${expectedIdleHours.toFixed(1)}h. ` +
+            `Consider processing ${ordered[0]?.id ?? 'large specs'} first.`;
+    return {
+        order: ordered.map((s) => s.id),
+        expectedIdleHours,
+        suggestion,
+    };
+}
+//# sourceMappingURL=spec-scheduler.js.map

package/dist/engine/spec-scheduler.js.map

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

package/dist/engine/spec-source-sync.d.ts

@@ -0,0 +1,14 @@
+import type { SpecBinding, SpecSyncResult } from '../types/index.js';
+export declare function detectMarkers(content: string): {
+    specId: string;
+    line: number;
+    style: SpecBinding['markerStyle'];
+}[];
+export declare function detectLanguage(filePath: string): string;
+export declare function computeSyncFromCode(projectPath: string, filePaths: string[], existingBindings: SpecBinding[]): Promise<{
+    result: SpecSyncResult;
+    newBindings: SpecBinding[];
+}>;
+export declare function buildMarkerComment(specId: string, language: string): string;
+export declare function buildSourceBinding(specId: string, filePath: string, lineNumber?: number): SpecBinding;
+//# sourceMappingURL=spec-source-sync.d.ts.map

package/dist/engine/spec-source-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-source-sync.d.ts","sourceRoot":"","sources":["../../src/engine/spec-source-sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAiB,MAAM,mBAAmB,CAAC;AAYpF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,GACd;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC,aAAa,CAAC,CAAA;CAAE,EAAE,CAgBvE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBvD;AAMD,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,gBAAgB,EAAE,WAAW,EAAE,GAC9B,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CAqEjE;AAMD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW3E;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,WAAW,CAsBb"}

package/dist/engine/spec-source-sync.js

@@ -0,0 +1,148 @@
+// engine/spec-source-sync.ts — Spec-as-Source sync logic (SPEC-349)
+import { readFile } from 'node:fs/promises';
+// ---------------------------------------------------------------------------
+// Marker detection
+// ---------------------------------------------------------------------------
+const MARKER_PATTERNS = [
+    { regex: /\/\/\s*@spec\s+(SPEC-\d+)/i, style: 'slashslash' },
+    { regex: /#\s*@spec\s+(SPEC-\d+)/i, style: 'hash' },
+    { regex: /--\s*@spec\s+(SPEC-\d+)/i, style: 'doubledash' },
+];
+export function detectMarkers(content) {
+    const results = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        for (const { regex, style } of MARKER_PATTERNS) {
+            const match = regex.exec(line);
+            if (match?.[1] !== undefined) {
+                results.push({ specId: match[1], line: i + 1, style });
+                break;
+            }
+        }
+    }
+    return results;
+}
+export function detectLanguage(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
+    const MAP = {
+        ts: 'typescript',
+        js: 'javascript',
+        tsx: 'typescript',
+        jsx: 'javascript',
+        py: 'python',
+        rb: 'ruby',
+        go: 'go',
+        rs: 'rust',
+        java: 'java',
+        kt: 'kotlin',
+        swift: 'swift',
+        cs: 'csharp',
+        php: 'php',
+        sh: 'shell',
+        sql: 'sql',
+    };
+    return MAP[ext] ?? 'unknown';
+}
+// ---------------------------------------------------------------------------
+// Sync from code (pure — receives existing bindings, returns new state)
+// ---------------------------------------------------------------------------
+export async function computeSyncFromCode(projectPath, filePaths, existingBindings) {
+    const now = new Date().toISOString();
+    const errors = [];
+    let bindingsFound = 0;
+    let bindingsCreated = 0;
+    let bindingsUpdated = 0;
+    const newBindings = [];
+    for (const filePath of filePaths) {
+        let content;
+        try {
+            content = await readFile(filePath, 'utf-8');
+        }
+        catch (err) {
+            errors.push(`Cannot read ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const markers = detectMarkers(content);
+        bindingsFound += markers.length;
+        for (const { specId, line, style } of markers) {
+            const existing = existingBindings.find((b) => b.filePath === filePath && b.specId === specId);
+            if (existing !== undefined) {
+                const updated = {
+                    ...existing,
+                    lineNumber: line,
+                    markerStyle: style,
+                    status: 'active',
+                    updatedAt: now,
+                };
+                newBindings.push(updated);
+                bindingsUpdated++;
+            }
+            else {
+                const created = {
+                    id: `bind-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+                    specId,
+                    filePath,
+                    lineNumber: line,
+                    language: detectLanguage(filePath),
+                    markerStyle: style,
+                    status: 'active',
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                newBindings.push(created);
+                bindingsCreated++;
+            }
+        }
+    }
+    // Mark existing bindings not found in scanned files as stale
+    const scannedSet = new Set(filePaths);
+    const preserved = existingBindings.filter((b) => !scannedSet.has(b.filePath));
+    const stale = preserved.map((b) => ({ ...b, status: 'stale' }));
+    const result = {
+        projectPath,
+        syncedAt: now,
+        scannedFiles: filePaths.length,
+        bindingsFound,
+        bindingsCreated,
+        bindingsUpdated,
+        bindingsRemoved: 0,
+        errors,
+    };
+    return { result, newBindings: [...newBindings, ...stale] };
+}
+// ---------------------------------------------------------------------------
+// Mark as source (pure — returns binding to save)
+// ---------------------------------------------------------------------------
+export function buildMarkerComment(specId, language) {
+    const hashLangs = new Set(['python', 'ruby', 'shell', 'yaml', 'toml', 'r']);
+    const dashLangs = new Set(['sql', 'haskell', 'lua']);
+    if (hashLangs.has(language)) {
+        return `# @spec ${specId}`;
+    }
+    if (dashLangs.has(language)) {
+        return `-- @spec ${specId}`;
+    }
+    return `// @spec ${specId}`;
+}
+export function buildSourceBinding(specId, filePath, lineNumber) {
+    const now = new Date().toISOString();
+    const language = detectLanguage(filePath);
+    const markerStyle = language === 'python' || language === 'ruby' || language === 'shell'
+        ? 'hash'
+        : language === 'sql'
+            ? 'doubledash'
+            : 'slashslash';
+    return {
+        id: `bind-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        specId,
+        filePath,
+        lineNumber,
+        language,
+        markerStyle,
+        status: 'active',
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+//# sourceMappingURL=spec-source-sync.js.map

package/dist/engine/spec-source-sync.js.map

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

package/dist/engine/tech-debt-manager.d.ts

@@ -0,0 +1,12 @@
+import type { TechDebtEntry, TechDebtConfig, TechDebtForecast, TechDebtMetrics } from '../types/index.js';
+/** Generate a simple UUID-like ID for a tech debt item. */
+export declare function generateDebtId(): string;
+/** Compute summary metrics from a list of tech debt items. */
+export declare function computeTechDebtMetrics(items: TechDebtEntry[]): TechDebtMetrics;
+/** Forecast tech debt growth given current items and config. */
+export declare function forecastTechDebt(items: TechDebtEntry[], config: TechDebtConfig): TechDebtForecast;
+/** Generate a simple HTML report of tech debt. */
+export declare function generateTechDebtReport(items: TechDebtEntry[], config: TechDebtConfig): string;
+/** Filter tech debt items by status and/or severity and/or category. */
+export declare function filterDebtItems(items: TechDebtEntry[], status?: string, severity?: string, category?: string): TechDebtEntry[];
+//# sourceMappingURL=tech-debt-manager.d.ts.map

package/dist/engine/tech-debt-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tech-debt-manager.d.ts","sourceRoot":"","sources":["../../src/engine/tech-debt-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAM3B,2DAA2D;AAC3D,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAMD,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,eAAe,CAoB9E;AA6BD,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,gBAAgB,CA4BjG;AAMD,kDAAkD;AAClD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAyD7F;AAMD,wEAAwE;AACxE,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EAAE,EACtB,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,EAAE,CAYjB"}