@kynetic-ai/spec 0.1.0

package/dist/parser/items.js

@@ -0,0 +1,321 @@
+/**
+ * Item index for efficient queries across spec items and tasks.
+ *
+ * Provides filtering by type, tags, status, and field presence.
+ * Complements ReferenceIndex which handles @reference resolution.
+ */
+import { grepItem } from '../utils/grep.js';
+// ============================================================
+// ITEM INDEX
+// ============================================================
+/**
+ * Index for efficient item queries.
+ * Build once when loading the spec, then query many times.
+ */
+export class ItemIndex {
+    /** All items (tasks + spec items) */
+    allItems = [];
+    /** Tasks only */
+    tasks = [];
+    /** Spec items only (non-tasks) */
+    specItems = [];
+    /** Index by type */
+    typeIndex = new Map();
+    /** Index by tag */
+    tagIndex = new Map();
+    /** Index by task status */
+    statusIndex = new Map();
+    /** Index by maturity */
+    maturityIndex = new Map();
+    /** Index by implementation status */
+    implementationIndex = new Map();
+    /**
+     * Build index from loaded items
+     */
+    constructor(tasks, items) {
+        this.tasks = tasks;
+        this.specItems = items;
+        this.allItems = [...tasks, ...items];
+        // Build indexes
+        for (const item of this.allItems) {
+            this.indexItem(item);
+        }
+    }
+    indexItem(item) {
+        // Index by type
+        const type = item.type || 'unknown';
+        const typeList = this.typeIndex.get(type) || [];
+        typeList.push(item);
+        this.typeIndex.set(type, typeList);
+        // Index by tags
+        const tags = 'tags' in item ? item.tags : [];
+        for (const tag of tags) {
+            const tagList = this.tagIndex.get(tag) || [];
+            tagList.push(item);
+            this.tagIndex.set(tag, tagList);
+        }
+        // Index tasks by status
+        if ('status' in item && typeof item.status === 'string') {
+            const task = item;
+            const statusList = this.statusIndex.get(task.status) || [];
+            statusList.push(task);
+            this.statusIndex.set(task.status, statusList);
+        }
+        // Index spec items by maturity/implementation
+        if ('status' in item && typeof item.status === 'object' && item.status !== null) {
+            const specItem = item;
+            const status = specItem.status;
+            if (status.maturity) {
+                const maturityList = this.maturityIndex.get(status.maturity) || [];
+                maturityList.push(specItem);
+                this.maturityIndex.set(status.maturity, maturityList);
+            }
+            if (status.implementation) {
+                const implList = this.implementationIndex.get(status.implementation) || [];
+                implList.push(specItem);
+                this.implementationIndex.set(status.implementation, implList);
+            }
+        }
+    }
+    /**
+     * Query items with filters
+     */
+    query(filter = {}) {
+        let results;
+        // Start with appropriate base set
+        if (filter.tasksOnly) {
+            results = [...this.tasks];
+        }
+        else if (filter.specItemsOnly) {
+            results = [...this.specItems];
+        }
+        else {
+            results = [...this.allItems];
+        }
+        // Apply type filter
+        if (filter.type) {
+            const types = Array.isArray(filter.type) ? filter.type : [filter.type];
+            results = results.filter(item => types.includes(item.type));
+        }
+        // Apply tag filter (ANY)
+        if (filter.tags && filter.tags.length > 0) {
+            results = results.filter(item => {
+                const itemTags = 'tags' in item ? item.tags : [];
+                return filter.tags.some(tag => itemTags.includes(tag));
+            });
+        }
+        // Apply tag filter (ALL)
+        if (filter.allTags && filter.allTags.length > 0) {
+            results = results.filter(item => {
+                const itemTags = 'tags' in item ? item.tags : [];
+                return filter.allTags.every(tag => itemTags.includes(tag));
+            });
+        }
+        // Apply task status filter
+        if (filter.status) {
+            const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+            results = results.filter(item => {
+                if (!('status' in item) || typeof item.status !== 'string')
+                    return false;
+                return statuses.includes(item.status);
+            });
+        }
+        // Apply maturity filter
+        if (filter.maturity) {
+            const maturities = Array.isArray(filter.maturity) ? filter.maturity : [filter.maturity];
+            results = results.filter(item => {
+                if (!('status' in item) || typeof item.status !== 'object' || !item.status)
+                    return false;
+                const status = item.status;
+                return status.maturity && maturities.includes(status.maturity);
+            });
+        }
+        // Apply implementation filter
+        if (filter.implementation) {
+            const impls = Array.isArray(filter.implementation) ? filter.implementation : [filter.implementation];
+            results = results.filter(item => {
+                if (!('status' in item) || typeof item.status !== 'object' || !item.status)
+                    return false;
+                const status = item.status;
+                return status.implementation && impls.includes(status.implementation);
+            });
+        }
+        // Apply has-fields filter
+        if (filter.hasFields && filter.hasFields.length > 0) {
+            results = results.filter(item => {
+                const obj = item;
+                return filter.hasFields.every(field => {
+                    const value = getNestedField(obj, field);
+                    return value !== undefined && value !== null;
+                });
+            });
+        }
+        // Apply field-equals filter
+        if (filter.fieldEquals && filter.fieldEquals.length > 0) {
+            results = results.filter(item => {
+                const obj = item;
+                return filter.fieldEquals.every(({ field, value }) => {
+                    const itemValue = getNestedField(obj, field);
+                    return itemValue === value;
+                });
+            });
+        }
+        // Apply title search
+        if (filter.titleContains) {
+            const search = filter.titleContains.toLowerCase();
+            results = results.filter(item => item.title.toLowerCase().includes(search));
+        }
+        // Apply grep search (regex across all text content)
+        if (filter.grepSearch) {
+            results = results.filter(item => {
+                const match = grepItem(item, filter.grepSearch);
+                return match !== null;
+            });
+        }
+        return results;
+    }
+    /**
+     * Query with pagination
+     */
+    queryPaginated(filter = {}, offset = 0, limit = 50) {
+        const allResults = this.query(filter);
+        const items = allResults.slice(offset, offset + limit);
+        return {
+            items,
+            total: allResults.length,
+            offset,
+            limit,
+        };
+    }
+    /**
+     * Get items by type
+     */
+    getByType(type) {
+        return this.typeIndex.get(type) || [];
+    }
+    /**
+     * Get items by tag
+     */
+    getByTag(tag) {
+        return this.tagIndex.get(tag) || [];
+    }
+    /**
+     * Get tasks by status
+     */
+    getTasksByStatus(status) {
+        return this.statusIndex.get(status) || [];
+    }
+    /**
+     * Get spec items by maturity
+     */
+    getByMaturity(maturity) {
+        return this.maturityIndex.get(maturity) || [];
+    }
+    /**
+     * Get spec items by implementation status
+     */
+    getByImplementation(impl) {
+        return this.implementationIndex.get(impl) || [];
+    }
+    /**
+     * Get all unique types in the index
+     */
+    getTypes() {
+        return [...this.typeIndex.keys()].sort();
+    }
+    /**
+     * Get all unique tags in the index
+     */
+    getTags() {
+        return [...this.tagIndex.keys()].sort();
+    }
+    /**
+     * Get count by type
+     */
+    getTypeCounts() {
+        const counts = new Map();
+        for (const [type, items] of this.typeIndex) {
+            counts.set(type, items.length);
+        }
+        return counts;
+    }
+    /**
+     * Get count by tag
+     */
+    getTagCounts() {
+        const counts = new Map();
+        for (const [tag, items] of this.tagIndex) {
+            counts.set(tag, items.length);
+        }
+        return counts;
+    }
+    /**
+     * Get total item count
+     */
+    get size() {
+        return this.allItems.length;
+    }
+    /**
+     * Get task count
+     */
+    get taskCount() {
+        return this.tasks.length;
+    }
+    /**
+     * Get spec item count
+     */
+    get specItemCount() {
+        return this.specItems.length;
+    }
+}
+// ============================================================
+// HELPERS
+// ============================================================
+/**
+ * Get a nested field value using dot notation
+ * e.g., "status.maturity" -> item.status.maturity
+ */
+function getNestedField(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Find direct child items of a parent item based on _path
+ * Children have paths like "parent_path.field[N]"
+ */
+export function findChildItems(parent, allItems) {
+    // Handle both cases: parent at root and nested parent
+    const parentPath = parent._path || '';
+    // Look for items whose path starts with parent's path
+    return allItems.filter(item => {
+        if (!item._path)
+            return false;
+        if (item._ulid === parent._ulid)
+            return false; // Skip self
+        // Child path should be: parentPath.field[N]
+        // Examples:
+        // - Parent: "features[0]", Child: "features[0].requirements[0]"
+        // - Parent: "", Child: "features[0]"
+        if (parentPath === '') {
+            // Root level parent - children are top-level items like "features[0]"
+            return !item._path.includes('.');
+        }
+        // Nested parent - children start with parent path + dot
+        if (!item._path.startsWith(parentPath + '.')) {
+            return false;
+        }
+        // Must be direct child (no additional nesting)
+        // Remove parent prefix and check for no more dots
+        const remainder = item._path.slice(parentPath.length + 1);
+        return !remainder.includes('.');
+    });
+}
+//# sourceMappingURL=items.js.map

package/dist/parser/items.js.map

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

package/dist/parser/meta.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Meta manifest loading and operations.
+ *
+ * The meta manifest (kynetic.meta.yaml) contains process definitions:
+ * - Agents: roles, capabilities, conventions
+ * - Workflows: structured processes with steps
+ * - Conventions: project rules and standards
+ * - Observations: feedback about processes
+ */
+import { type MetaManifest, type Agent, type Workflow, type Convention, type Observation, type MetaItem, type ObservationType, type SessionContext, getMetaItemType } from '../schema/index.js';
+import type { KspecContext } from './yaml.js';
+/**
+ * Loaded agent with runtime metadata
+ */
+export interface LoadedAgent extends Agent {
+    _sourceFile?: string;
+}
+/**
+ * Loaded workflow with runtime metadata
+ */
+export interface LoadedWorkflow extends Workflow {
+    _sourceFile?: string;
+}
+/**
+ * Loaded convention with runtime metadata
+ */
+export interface LoadedConvention extends Convention {
+    _sourceFile?: string;
+}
+/**
+ * Loaded observation with runtime metadata
+ */
+export interface LoadedObservation extends Observation {
+    _sourceFile?: string;
+}
+/**
+ * Any loaded meta item
+ */
+export type LoadedMetaItem = LoadedAgent | LoadedWorkflow | LoadedConvention | LoadedObservation;
+/**
+ * Meta context containing all loaded meta items
+ */
+export interface MetaContext {
+    manifest: MetaManifest | null;
+    manifestPath: string | null;
+    agents: LoadedAgent[];
+    workflows: LoadedWorkflow[];
+    conventions: LoadedConvention[];
+    observations: LoadedObservation[];
+}
+/**
+ * Find the meta manifest file (kynetic.meta.yaml)
+ */
+export declare function findMetaManifest(specDir: string): Promise<string | null>;
+/**
+ * Get the meta manifest file path.
+ * Returns path even if file doesn't exist yet.
+ */
+export declare function getMetaManifestPath(ctx: KspecContext): string;
+/**
+ * Load the meta context from a kspec context.
+ * Loads meta manifest and follows includes.
+ */
+export declare function loadMetaContext(ctx: KspecContext): Promise<MetaContext>;
+/**
+ * Get meta stats summary
+ */
+export declare function getMetaStats(meta: MetaContext): {
+    agents: number;
+    workflows: number;
+    conventions: number;
+    observations: number;
+    unresolvedObservations: number;
+};
+/**
+ * Find a meta item by reference (ULID, short ULID, or id)
+ */
+export declare function findMetaItemByRef(meta: MetaContext, ref: string): LoadedMetaItem | undefined;
+/**
+ * Determine if an item is a meta item type
+ */
+export declare function isMetaItemType(type: string): boolean;
+/**
+ * Create a new observation
+ */
+export declare function createObservation(type: ObservationType, content: string, options?: {
+    workflow_ref?: string;
+    author?: string;
+}): Observation;
+/**
+ * Save an observation to the meta manifest
+ */
+export declare function saveObservation(ctx: KspecContext, observation: LoadedObservation): Promise<void>;
+/**
+ * Delete an observation from the meta manifest
+ */
+export declare function deleteObservation(ctx: KspecContext, ulid: string): Promise<boolean>;
+export { getMetaItemType };
+export type { Agent, Workflow, Convention, Observation, MetaItem };
+/**
+ * Save any meta item (agent, workflow, convention) to the manifest
+ */
+export declare function saveMetaItem(ctx: KspecContext, item: LoadedMetaItem, itemType: 'agent' | 'workflow' | 'convention'): Promise<void>;
+/**
+ * Delete any meta item from the manifest
+ */
+export declare function deleteMetaItem(ctx: KspecContext, itemUlid: string, itemType: 'agent' | 'workflow' | 'convention' | 'observation'): Promise<boolean>;
+/**
+ * Get the session context file path
+ */
+export declare function getSessionContextPath(ctx: KspecContext): string;
+/**
+ * Load session context (or return empty context if not exists)
+ */
+export declare function loadSessionContext(ctx: KspecContext): Promise<SessionContext>;
+/**
+ * Save session context
+ */
+export declare function saveSessionContext(ctx: KspecContext, context: SessionContext): Promise<void>;
+//# sourceMappingURL=meta.d.ts.map

package/dist/parser/meta.d.ts.map

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