@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/service/TechDebtService.js

@@ -0,0 +1,337 @@
+/**
+ * TechDebtService
+ *
+ * Manages technical debt items stored in git.
+ * Scans tech-debt documents recursively from the resolved repo layout.
+ * Extends TrackedDocumentService to provide filtering, sorting, and query capabilities.
+ */
+import matter from 'gray-matter';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { isCategory, isSeverity, isTechDebtStatus, parseTechDebt, } from '#tech-debt/index';
+import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { resolveTechDebtRoot } from '#utils/tech-debt-root';
+import { calculateFreshness } from '#utils/freshness';
+import { toBlueprintRecord } from './blueprint-records.js';
+import { linkBlueprintToTechDebt, unlinkBlueprintFromTechDebt, } from './blueprint-tech-debt-links.js';
+import { computePriorityScore as computePriorityScoreAlgorithm } from './priority-scoring.js';
+import { scanBlueprintDirectory, scanDocumentDirectory } from './scanner.js';
+import { TrackedDocumentService } from './TrackedDocumentService.js';
+export class TechDebtService extends TrackedDocumentService {
+    constructor(projectPath) {
+        // Resolve generic consumer layout first, with Webpresso's legacy layout as fallback.
+        const techDebtDir = resolveTechDebtRoot(projectPath);
+        super(techDebtDir, 'README.md', projectPath);
+    }
+    // Implementation of abstract list() method
+    list() {
+        return this.listTechDebt();
+    }
+    async listTechDebt() {
+        const scannedItems = scanDocumentDirectory({
+            baseDir: this.baseDir,
+            filePattern: this.filePattern,
+            includeSpecialFolders: true,
+        });
+        const items = [];
+        for (const scanned of scannedItems) {
+            const summary = await this.tryParseTechDebtSummary(scanned);
+            if (summary) {
+                items.push(summary);
+            }
+        }
+        return items;
+    }
+    async tryParseTechDebtSummary(scanned) {
+        try {
+            const content = await fs.readFile(scanned.path, 'utf-8');
+            return this.parseSummary(content, scanned.slug);
+        }
+        catch (error) {
+            return this.handleParseSummaryError(error, scanned);
+        }
+    }
+    parseSummary(content, slug) {
+        const item = parseTechDebt(content, slug);
+        return {
+            slug: item.slug,
+            title: item.title,
+            status: item.status,
+            severity: item.severity,
+            category: item.category,
+            priorityScore: item.basePriority,
+            nextReview: item.nextReview,
+        };
+    }
+    buildMalformedSummary(scanned, data, errorMessage) {
+        return {
+            slug: scanned.slug,
+            title: data.title || scanned.slug,
+            status: data.status || 'unknown',
+            severity: data.severity || 'unknown',
+            category: data.category,
+            priorityScore: 0,
+            malformed: errorMessage,
+        };
+    }
+    // Implementation of abstract get() method
+    get(slug) {
+        return this.getTechDebt(slug);
+    }
+    async getTechDebt(slug) {
+        // Try direct path first (supports both 'category/item' and 'item')
+        const itemPath = path.join(this.baseDir, slug, 'README.md');
+        try {
+            await fs.access(itemPath);
+            const content = await fs.readFile(itemPath, 'utf-8');
+            return parseTechDebt(content, slug);
+        }
+        catch {
+            // Scan all items to find a match by slug
+            const scannedItems = scanDocumentDirectory({
+                baseDir: this.baseDir,
+                filePattern: this.filePattern,
+                includeSpecialFolders: true,
+            });
+            const found = scannedItems.find((p) => p.slug === slug || p.slug.endsWith(`/${slug}`));
+            if (!found) {
+                throw new Error(`TechDebt item not found: ${slug}\nAvailable items:\n${scannedItems.map((p) => `  - ${p.slug}`).join('\n')}`);
+            }
+            const content = await fs.readFile(found.path, 'utf-8');
+            return parseTechDebt(content, found.slug);
+        }
+    }
+    async query(options) {
+        const scannedItems = scanDocumentDirectory({
+            baseDir: this.baseDir,
+            filePattern: this.filePattern,
+        });
+        const itemRecords = await this.buildRecords(scannedItems);
+        const { records, totalFiltered } = this.processQueryPipeline(itemRecords, options);
+        return {
+            items: records,
+            summary: this.computeQuerySummary(itemRecords, totalFiltered),
+        };
+    }
+    /**
+     * Get tech debt items that are past their review date
+     */
+    async getOverdueReviews() {
+        const result = await this.query({
+            filters: { overdue: true },
+        });
+        return result.items;
+    }
+    /**
+     * Get tech debt items by category
+     */
+    async getByCategory(category) {
+        if (!isCategory(category)) {
+            throw new Error(`Invalid category: ${category}`);
+        }
+        const result = await this.query({
+            filters: { category },
+        });
+        return result.items;
+    }
+    /**
+     * Get tech debt items by severity
+     */
+    async getBySeverity(severity) {
+        if (!isSeverity(severity)) {
+            throw new Error(`Invalid severity: ${severity}`);
+        }
+        const result = await this.query({
+            filters: { severity },
+        });
+        return result.items;
+    }
+    /**
+     * Link a tech debt item to a blueprint (bidirectional)
+     * Updates both the tech debt document and blueprint frontmatter
+     * @param tdSlug - TechDebt slug
+     * @param bpSlug - Blueprint slug
+     * @throws Error if either document doesn't exist
+     */
+    async linkToBlueprint(tdSlug, bpSlug) {
+        // Verify both documents exist
+        const itemPath = path.join(this.baseDir, tdSlug, 'README.md');
+        await fs.access(itemPath); // Throws if tech debt not found
+        await linkBlueprintToTechDebt(resolveBlueprintRoot(this.projectPath), this.projectPath, bpSlug, tdSlug);
+    }
+    /**
+     * Unlink a tech debt item from a blueprint (bidirectional)
+     * Updates both the tech debt document and blueprint frontmatter
+     * @param tdSlug - TechDebt slug
+     * @param bpSlug - Blueprint slug
+     */
+    async unlinkFromBlueprint(tdSlug, bpSlug) {
+        await unlinkBlueprintFromTechDebt(resolveBlueprintRoot(this.projectPath), this.projectPath, bpSlug, tdSlug);
+    }
+    /**
+     * Get all blueprints linked to a tech debt item
+     * @param tdSlug - TechDebt slug
+     * @returns Array of BlueprintRecord objects
+     */
+    async getLinkedBlueprints(tdSlug) {
+        // Read fresh from disk and deep-clone to avoid gray-matter shared state issues
+        const itemPath = path.join(this.baseDir, tdSlug, 'README.md');
+        const content = await fs.readFile(itemPath, 'utf-8');
+        const parsed = matter(content);
+        const data = JSON.parse(JSON.stringify(parsed.data));
+        const linkedBlueprints = data.linked_blueprints ?? [];
+        if (!linkedBlueprints.length) {
+            return [];
+        }
+        const blueprintsDir = resolveBlueprintRoot(this.projectPath);
+        const scannedBlueprints = scanBlueprintDirectory({
+            baseDir: blueprintsDir,
+            includeSpecialFolders: true,
+        });
+        const matchingBlueprints = scannedBlueprints.filter((blueprint) => linkedBlueprints.includes(blueprint.slug) ||
+            linkedBlueprints.some((linked) => blueprint.slug.endsWith(`/${linked}`)));
+        const records = await Promise.all(matchingBlueprints.map((blueprint) => toBlueprintRecord(blueprint.path, blueprint.slug, blueprint.group)));
+        return records.filter((record) => record !== null);
+    }
+    /**
+     * Compute priority score for a tech debt item
+     *
+     * Calculates a 0-100 priority score based on:
+     * - Severity (10-40 points)
+     * - Staleness (0-30 points) - days since last review
+     * - Overdue review (0-20 points)
+     * - Active blueprint link (0-10 points)
+     * - Category urgency (0-5 points) - security=5, testing=3
+     *
+     * @param item - The tech debt record to score
+     * @param linkedBlueprints - Blueprints that reference this tech debt item
+     * @returns Priority score from 0-100 (higher = more urgent)
+     */
+    computePriorityScore(item, linkedBlueprints) {
+        return computePriorityScoreAlgorithm(item, linkedBlueprints);
+    }
+    static FRESHNESS_STATUS_MAP = {
+        accepted: 'planned',
+        'needs-remediation': 'in-progress',
+        monitoring: 'planned',
+        resolved: 'completed',
+    };
+    static computeFreshness(lastReviewed, status) {
+        const freshnessStatus = TechDebtService.FRESHNESS_STATUS_MAP[status] ?? 'in-progress';
+        return lastReviewed
+            ? calculateFreshness(lastReviewed, freshnessStatus)
+            : { score: 0.5, daysSinceUpdate: 0, status: 'aging' };
+    }
+    async toRecord(filePath, slug, group) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const item = parseTechDebt(content, slug);
+            const lastReviewed = item.lastReviewed ? new Date(item.lastReviewed) : undefined;
+            const validCategory = item.category && isCategory(item.category) ? item.category : undefined;
+            return {
+                slug,
+                title: item.title,
+                status: isTechDebtStatus(item.status) ? item.status : 'needs-remediation',
+                severity: isSeverity(item.severity) ? item.severity : 'medium',
+                category: validCategory,
+                priorityScore: item.basePriority,
+                nextReview: item.nextReview,
+                group,
+                path: filePath,
+                lastReviewed,
+                freshness: TechDebtService.computeFreshness(lastReviewed, item.status),
+                linkedBlueprints: item.linkedBlueprints ?? [],
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    matchesAllFilters(item, filters) {
+        return (this.matchesStatusFilter(item.status, filters.status) &&
+            this.matchesSeverityFilter(item, filters) &&
+            this.matchesCategoryFilter(item, filters) &&
+            this.matchesOverdueFilter(item, filters) &&
+            this.matchesStaleDaysFilter(item, filters));
+    }
+    matchesSeverityFilter(item, filters) {
+        return this.matchesFilter(item.severity, filters.severity);
+    }
+    matchesCategoryFilter(item, filters) {
+        if (!filters.category)
+            return true;
+        return item.category !== undefined && this.matchesFilter(item.category, filters.category);
+    }
+    matchesOverdueFilter(item, filters) {
+        if (!filters.overdue)
+            return true;
+        if (!item.nextReview)
+            return false;
+        const nextReviewDate = new Date(item.nextReview);
+        return nextReviewDate < new Date();
+    }
+    matchesStaleDaysFilter(item, filters) {
+        if (filters.staleDays === undefined)
+            return true;
+        if (!item.lastReviewed)
+            return false;
+        const daysSinceReview = Math.floor((Date.now() - item.lastReviewed.getTime()) / (1000 * 60 * 60 * 24));
+        return daysSinceReview >= filters.staleDays;
+    }
+    static SEVERITY_ORDER = { critical: 4, high: 3, medium: 2, low: 1 };
+    static compareOptionalDates(a, b) {
+        if (!a && !b)
+            return 0;
+        if (!a)
+            return 1;
+        if (!b)
+            return -1;
+        const aTime = a instanceof Date ? a.getTime() : new Date(a).getTime();
+        const bTime = b instanceof Date ? b.getTime() : new Date(b).getTime();
+        return aTime - bTime;
+    }
+    static compareField(a, b, field) {
+        switch (field) {
+            case 'priorityScore':
+                return a.priorityScore - b.priorityScore;
+            case 'nextReview':
+                return TechDebtService.compareOptionalDates(a.nextReview, b.nextReview);
+            case 'lastReviewed':
+                return TechDebtService.compareOptionalDates(a.lastReviewed, b.lastReviewed);
+            case 'slug':
+                return a.slug.localeCompare(b.slug);
+            case 'severity':
+                return ((TechDebtService.SEVERITY_ORDER[a.severity] ?? 0) -
+                    (TechDebtService.SEVERITY_ORDER[b.severity] ?? 0));
+            default:
+                return 0;
+        }
+    }
+    applySorting(items, sort) {
+        const sorted = [...items];
+        const direction = sort.direction === 'asc' ? 1 : -1;
+        sorted.sort((a, b) => TechDebtService.compareField(a, b, sort.field) * direction);
+        return sorted;
+    }
+    // Compute query summary
+    computeQuerySummary(allItems, totalFiltered) {
+        const byStatus = this.countByField(allItems, (i) => i.status);
+        const bySeverity = this.countByField(allItems, (i) => i.severity);
+        const now = new Date();
+        const overdueCount = allItems.filter((i) => {
+            if (!i.nextReview)
+                return false;
+            const nextReviewDate = new Date(i.nextReview);
+            return nextReviewDate < now;
+        }).length;
+        const totalPriority = allItems.reduce((sum, i) => sum + i.priorityScore, 0);
+        return {
+            total: totalFiltered,
+            byStatus,
+            bySeverity,
+            overdueCount,
+            avgPriority: allItems.length > 0 ? totalPriority / allItems.length : 0,
+        };
+    }
+}
+//# sourceMappingURL=TechDebtService.js.map

package/dist/esm/blueprint/service/TrackedDocumentService.d.ts

@@ -0,0 +1,198 @@
+/**
+ * TrackedDocumentService - Abstract base class for tracked document services
+ *
+ * This base class provides shared functionality for services that manage
+ * tracked documents stored in git (e.g., blueprints, tech debt items).
+ *
+ * Uses the Template Method pattern:
+ * - Base class provides skeleton operations (list, get, query, filter, sort)
+ * - Subclasses implement document-specific logic (parseSummary, toRecord)
+ *
+ * @template TSummary - Lightweight summary type for list views
+ * @template TRecord - Extended record type with query/filter fields
+ * @template TFilters - Filter criteria specific to the document type
+ * @template TSortOptions - Sorting options specific to the document type
+ */
+import type { FreshnessScore } from '#query/types';
+import type { ScannedBlueprint } from './scanner.js';
+/**
+ * Base query options that all tracked document services support
+ */
+export interface BaseQueryOptions<TFilters, TSortOptions> {
+    filters?: TFilters;
+    sort?: TSortOptions;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Base query result structure returned by all tracked document services.
+ * Subclasses define their own result shape with domain-specific field names
+ * (e.g., 'plans' for blueprints, 'items' for tech debt).
+ */
+export interface BaseQueryResult<TSummary> {
+    /** Aggregate summary statistics */
+    summary: TSummary;
+}
+/**
+ * Abstract base class for services that manage tracked documents.
+ *
+ * Provides:
+ * - Directory scanning and file discovery
+ * - Filtering and sorting operations
+ * - Summary computation helpers
+ * - Template methods for subclass-specific logic
+ */
+export declare abstract class TrackedDocumentService<TSummary, TRecord extends {
+    freshness: FreshnessScore;
+}, TFilters, TSortOptions, TQueryResult extends BaseQueryResult<unknown> = BaseQueryResult<unknown>> {
+    /**
+     * Base directory containing tracked documents (absolute or relative to repo root)
+     */
+    protected readonly baseDir: string;
+    /**
+     * File pattern to match (e.g., '_overview.md', 'README.md')
+     */
+    protected readonly filePattern: string;
+    /**
+     * Project root path for cross-service references (e.g., cross-linking).
+     * When provided, used to construct sibling service instances.
+     */
+    protected readonly projectPath: string | undefined;
+    /**
+     * @param baseDir - Directory containing tracked documents
+     * @param filePattern - Filename pattern to scan for
+     * @param projectPath - Optional project root path for cross-service references
+     */
+    constructor(baseDir: string, filePattern: string, projectPath?: string);
+    /**
+     * List all documents as lightweight summaries.
+     * Subclasses must implement parseSummary() to extract summary data.
+     *
+     * @returns Array of document summaries
+     */
+    abstract list(): Promise<TSummary[]>;
+    /**
+     * Get a single document by its unique identifier.
+     * Subclasses must implement document-specific retrieval logic.
+     *
+     * @param id - Unique identifier (e.g., slug, path)
+     * @returns Full document data
+     */
+    abstract get(id: string): Promise<unknown>;
+    /**
+     * Query documents with filtering, sorting, and pagination.
+     * Subclasses must implement toRecord() to convert documents to queryable records.
+     *
+     * @param options - Query options (filters, sort, pagination)
+     * @returns Query result with records and summary
+     */
+    abstract query(options?: BaseQueryOptions<TFilters, TSortOptions>): Promise<TQueryResult>;
+    /**
+     * Parse document content into a summary record.
+     * Subclasses implement document-specific parsing logic.
+     *
+     * @param content - Raw file content
+     * @param id - Document identifier
+     * @returns Parsed summary or null if parsing fails
+     */
+    protected abstract parseSummary(content: string, id: string): TSummary | null;
+    /**
+     * Convert document to a full record with query fields.
+     * Subclasses implement document-specific transformation logic.
+     *
+     * @param filePath - Path to document file
+     * @param id - Document identifier
+     * @param group - Parent group/category (if applicable)
+     * @returns Record with query fields or null if conversion fails
+     */
+    protected abstract toRecord(filePath: string, id: string, group: string | null): Promise<TRecord | null>;
+    /**
+     * Apply filters to a list of records.
+     * Uses matchesAllFilters() which subclasses must implement.
+     *
+     * @param records - Records to filter
+     * @param filters - Filter criteria
+     * @returns Filtered records
+     */
+    protected applyFilters(records: TRecord[], filters: TFilters): TRecord[];
+    /**
+     * Check if a record matches all filter criteria.
+     * Subclasses implement document-specific filter logic.
+     *
+     * @param record - Record to check
+     * @param filters - Filter criteria
+     * @returns True if record matches all filters
+     */
+    protected abstract matchesAllFilters(record: TRecord, filters: TFilters): boolean;
+    /**
+     * Apply sorting to a list of records.
+     * Subclasses implement document-specific sort logic.
+     *
+     * @param records - Records to sort
+     * @param sort - Sort options
+     * @returns Sorted records
+     */
+    protected abstract applySorting(records: TRecord[], sort: TSortOptions): TRecord[];
+    /**
+     * Helper: Count records by a field value.
+     * Useful for computing summary statistics (e.g., byStatus, byGroup).
+     *
+     * @param records - Records to count
+     * @param getField - Function to extract field value from record
+     * @returns Map of field values to counts
+     */
+    protected countByField<T extends TRecord>(records: T[], getField: (record: T) => string): Record<string, number>;
+    /**
+     * Helper: Check if a record is stale based on freshness score.
+     * Common logic shared across all tracked document types.
+     *
+     * @param record - Record with freshness score
+     * @returns True if record is stale or critical
+     */
+    protected isStale(record: TRecord): boolean;
+    /**
+     * Helper: Check if a value matches a filter (single or array).
+     * Handles both single values and arrays with OR logic.
+     *
+     * @param value - Value to check
+     * @param filter - Filter value (single or array)
+     * @returns True if value matches filter
+     */
+    protected matchesFilter<T>(value: T, filter: T | T[] | undefined): boolean;
+    /**
+     * Check if a record's status matches the status filter.
+     * Uses matchesFilter for single/array value handling.
+     */
+    protected matchesStatusFilter(status: string, filter: string | string[] | undefined): boolean;
+    /**
+     * Build a malformed summary from frontmatter data and error message.
+     * Subclasses implement document-specific summary construction.
+     */
+    protected abstract buildMalformedSummary(scanned: {
+        path: string;
+        slug: string;
+    }, data: Record<string, unknown>, errorMessage: string): TSummary;
+    /**
+     * Handle parse errors when building summaries.
+     * Provides graceful degradation for ZodError and generic Error types.
+     * Returns a malformed summary with error indicator, or null for unknown errors.
+     */
+    protected handleParseSummaryError(error: unknown, scanned: {
+        path: string;
+        slug: string;
+    }): Promise<TSummary | null>;
+    /**
+     * Build records from scanned documents by iterating and calling toRecord.
+     * Extracts the common scan→iterate→toRecord pattern from query methods.
+     */
+    protected buildRecords(scannedDocs: ScannedBlueprint[]): Promise<TRecord[]>;
+    /**
+     * Common query pipeline: filter, sort, and paginate records.
+     * Subclasses scan and build records, then pass them to this method.
+     */
+    protected processQueryPipeline(allRecords: TRecord[], options?: BaseQueryOptions<TFilters, TSortOptions>): {
+        records: TRecord[];
+        totalFiltered: number;
+    };
+}
+//# sourceMappingURL=TrackedDocumentService.d.ts.map

package/dist/esm/blueprint/service/TrackedDocumentService.js

@@ -0,0 +1,162 @@
+/**
+ * TrackedDocumentService - Abstract base class for tracked document services
+ *
+ * This base class provides shared functionality for services that manage
+ * tracked documents stored in git (e.g., blueprints, tech debt items).
+ *
+ * Uses the Template Method pattern:
+ * - Base class provides skeleton operations (list, get, query, filter, sort)
+ * - Subclasses implement document-specific logic (parseSummary, toRecord)
+ *
+ * @template TSummary - Lightweight summary type for list views
+ * @template TRecord - Extended record type with query/filter fields
+ * @template TFilters - Filter criteria specific to the document type
+ * @template TSortOptions - Sorting options specific to the document type
+ */
+import matter from 'gray-matter';
+import * as fs from 'node:fs/promises';
+import { ZodError } from 'zod';
+/**
+ * Abstract base class for services that manage tracked documents.
+ *
+ * Provides:
+ * - Directory scanning and file discovery
+ * - Filtering and sorting operations
+ * - Summary computation helpers
+ * - Template methods for subclass-specific logic
+ */
+export class TrackedDocumentService {
+    /**
+     * Base directory containing tracked documents (absolute or relative to repo root)
+     */
+    baseDir;
+    /**
+     * File pattern to match (e.g., '_overview.md', 'README.md')
+     */
+    filePattern;
+    /**
+     * Project root path for cross-service references (e.g., cross-linking).
+     * When provided, used to construct sibling service instances.
+     */
+    projectPath;
+    /**
+     * @param baseDir - Directory containing tracked documents
+     * @param filePattern - Filename pattern to scan for
+     * @param projectPath - Optional project root path for cross-service references
+     */
+    constructor(baseDir, filePattern, projectPath) {
+        this.baseDir = baseDir;
+        this.filePattern = filePattern;
+        this.projectPath = projectPath;
+    }
+    /**
+     * Apply filters to a list of records.
+     * Uses matchesAllFilters() which subclasses must implement.
+     *
+     * @param records - Records to filter
+     * @param filters - Filter criteria
+     * @returns Filtered records
+     */
+    applyFilters(records, filters) {
+        return records.filter((record) => this.matchesAllFilters(record, filters));
+    }
+    /**
+     * Helper: Count records by a field value.
+     * Useful for computing summary statistics (e.g., byStatus, byGroup).
+     *
+     * @param records - Records to count
+     * @param getField - Function to extract field value from record
+     * @returns Map of field values to counts
+     */
+    countByField(records, getField) {
+        const counts = {};
+        for (const record of records) {
+            const field = getField(record);
+            counts[field] = (counts[field] ?? 0) + 1;
+        }
+        return counts;
+    }
+    /**
+     * Helper: Check if a record is stale based on freshness score.
+     * Common logic shared across all tracked document types.
+     *
+     * @param record - Record with freshness score
+     * @returns True if record is stale or critical
+     */
+    isStale(record) {
+        return record.freshness.status === 'stale' || record.freshness.status === 'critical';
+    }
+    /**
+     * Helper: Check if a value matches a filter (single or array).
+     * Handles both single values and arrays with OR logic.
+     *
+     * @param value - Value to check
+     * @param filter - Filter value (single or array)
+     * @returns True if value matches filter
+     */
+    matchesFilter(value, filter) {
+        if (filter === undefined)
+            return true;
+        const filters = Array.isArray(filter) ? filter : [filter];
+        return filters.includes(value);
+    }
+    /**
+     * Check if a record's status matches the status filter.
+     * Uses matchesFilter for single/array value handling.
+     */
+    matchesStatusFilter(status, filter) {
+        return this.matchesFilter(status, filter);
+    }
+    /**
+     * Handle parse errors when building summaries.
+     * Provides graceful degradation for ZodError and generic Error types.
+     * Returns a malformed summary with error indicator, or null for unknown errors.
+     */
+    async handleParseSummaryError(error, scanned) {
+        if (error instanceof ZodError) {
+            const content = await fs.readFile(scanned.path, 'utf-8');
+            const { data } = matter(content);
+            const errorMessage = `Invalid frontmatter:\n${error.issues.map((e) => `  - ${e.path.join('.')}: ${e.message}`).join('\n')}`;
+            return this.buildMalformedSummary(scanned, data, errorMessage);
+        }
+        if (error instanceof Error) {
+            const content = await fs.readFile(scanned.path, 'utf-8');
+            const { data } = matter(content);
+            return this.buildMalformedSummary(scanned, data, error.message);
+        }
+        return null;
+    }
+    /**
+     * Build records from scanned documents by iterating and calling toRecord.
+     * Extracts the common scan→iterate→toRecord pattern from query methods.
+     */
+    async buildRecords(scannedDocs) {
+        const records = [];
+        for (const scanned of scannedDocs) {
+            const record = await this.toRecord(scanned.path, scanned.slug, scanned.group);
+            if (record) {
+                records.push(record);
+            }
+        }
+        return records;
+    }
+    /**
+     * Common query pipeline: filter, sort, and paginate records.
+     * Subclasses scan and build records, then pass them to this method.
+     */
+    processQueryPipeline(allRecords, options) {
+        let filtered = options?.filters ? this.applyFilters(allRecords, options.filters) : allRecords;
+        if (options?.sort) {
+            filtered = this.applySorting(filtered, options.sort);
+        }
+        const totalFiltered = filtered.length;
+        if (options?.offset) {
+            filtered = filtered.slice(options.offset);
+        }
+        if (options?.limit) {
+            filtered = filtered.slice(0, options.limit);
+        }
+        return { records: filtered, totalFiltered };
+    }
+}
+//# sourceMappingURL=TrackedDocumentService.js.map