@rengler33/prov 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Core type definitions for prov entities.
+ *
+ * These types represent the fundamental entities in the intent graph:
+ * specifications, constraints, plans, decisions, steps, and traces.
+ *
+ * All entities are content-addressable via SHA-256 hash.
+ *
+ * @see spec:core-model:v1
+ */
+/**
+ * SHA-256 content hash, represented as `sha256:{first-12-hex-chars}`.
+ * Used for content-addressable storage and change detection.
+ *
+ * @see req:hashing
+ */
+export type Hash = `sha256:${string}`;
+/**
+ * ISO 8601 timestamp string.
+ */
+export type Timestamp = string;
+/**
+ * Entity identifier types following the format `{type}:{name}` or `{type}:{parent}:{name}`.
+ * IDs are lowercase alphanumeric with hyphens and colons.
+ *
+ * @see req:identifiers
+ */
+export type SpecId = `spec:${string}:v${number}`;
+export type RequirementId = `req:${string}:${string}`;
+export type ConstraintId = `constraint:${string}:v${number}`;
+export type InvariantId = `inv:${string}:${string}`;
+export type PlanId = `plan:${string}:v${number}`;
+export type DecisionId = `dec:${string}:${string}`;
+export type StepId = `step:${string}:${number}`;
+export type TraceId = `trace:${string}`;
+/**
+ * Union of all entity ID types.
+ */
+export type EntityId = SpecId | RequirementId | ConstraintId | InvariantId | PlanId | DecisionId | StepId | TraceId;
+/**
+ * Entity status values.
+ */
+export type EntityStatus = 'draft' | 'active' | 'deprecated' | 'archived';
+/**
+ * Acceptance criteria for a requirement.
+ */
+export interface AcceptanceCriterion {
+    /** Human-readable description of what must be true */
+    readonly description: string;
+    /** Optional verification method (command, test ref, or assertion) */
+    readonly verification?: string;
+}
+/**
+ * Requirement is an atomic unit of intent within a spec.
+ *
+ * @see req:entity:requirement
+ */
+export interface Requirement {
+    /** Unique id in format `req:{spec}:{name}` */
+    readonly id: RequirementId;
+    /** Human-readable description */
+    readonly description: string;
+    /** Acceptance criteria that define when requirement is met */
+    readonly acceptance: readonly (string | AcceptanceCriterion)[];
+    /** Optional dependencies on other requirements */
+    readonly dependencies?: readonly RequirementId[];
+}
+/**
+ * Specification entity represents declarative intent.
+ *
+ * @see req:entity:spec
+ */
+export interface Spec {
+    /** Unique id in format `spec:{name}:v{version}` */
+    readonly id: SpecId;
+    /** Semantic version */
+    readonly version: string;
+    /** Human-readable title */
+    readonly title: string;
+    /** Entity status */
+    readonly status: EntityStatus;
+    /** Human-readable intent description */
+    readonly intent: string;
+    /** One or more requirements */
+    readonly requirements: readonly Requirement[];
+    /** Content hash (computed, not stored in YAML) */
+    readonly hash?: Hash;
+}
+/**
+ * Verification method for an invariant.
+ */
+export interface VerificationMethod {
+    /** Type of verification */
+    readonly type: 'command' | 'test' | 'assertion' | 'manual';
+    /** Command to run, test reference, or assertion expression */
+    readonly value: string;
+    /** Expected outcome for command verification (e.g., 'success', 'failure', or custom pattern) */
+    readonly expect?: string;
+}
+/**
+ * Invariant is an atomic rule within a constraint.
+ *
+ * @see req:entity:invariant
+ */
+export interface Invariant {
+    /** Unique id in format `inv:{constraint}:{name}` */
+    readonly id: InvariantId;
+    /** What must always be true */
+    readonly rule: string;
+    /** How to verify compliance */
+    readonly verification: VerificationMethod;
+    /** Whether violation blocks plan execution */
+    readonly blocking?: boolean;
+}
+/**
+ * Constraint represents an invariant that must hold.
+ *
+ * @see req:entity:constraint
+ */
+export interface Constraint {
+    /** Unique id in format `constraint:{name}:v{version}` */
+    readonly id: ConstraintId;
+    /** Semantic version */
+    readonly version: string;
+    /** Human-readable title */
+    readonly title: string;
+    /** Entity status */
+    readonly status: EntityStatus;
+    /** Human-readable description of the constraint's purpose */
+    readonly description: string;
+    /** One or more invariants */
+    readonly invariants: readonly Invariant[];
+    /** Content hash (computed, not stored in YAML) */
+    readonly hash?: Hash;
+}
+/**
+ * Decision records a choice made during planning.
+ *
+ * @see req:entity:decision
+ */
+export interface Decision {
+    /** Unique id in format `dec:{plan}:{name}` */
+    readonly id: DecisionId;
+    /** The question being resolved */
+    readonly question: string;
+    /** The choice made */
+    readonly choice: string;
+    /** Rationale for the decision */
+    readonly rationale: string;
+    /** Requirements/constraints that motivated this decision */
+    readonly tracesTo: readonly (RequirementId | InvariantId)[];
+}
+/**
+ * Step is an actionable unit of implementation work.
+ *
+ * @see req:entity:step
+ */
+export interface Step {
+    /** Unique id in format `step:{plan}:{number}` */
+    readonly id: StepId;
+    /** Step number within the plan */
+    readonly number: number;
+    /** Concrete action to take */
+    readonly action: string;
+    /** Detailed description of what to do */
+    readonly description?: string;
+    /** Decisions, requirements, and invariants this step implements */
+    readonly tracesTo: readonly (DecisionId | RequirementId | InvariantId)[];
+    /** Dependencies on other steps (must complete first) */
+    readonly dependencies?: readonly StepId[];
+    /** Expected artifacts produced by this step */
+    readonly artifacts?: readonly string[];
+    /** Step completion status */
+    readonly status?: 'pending' | 'in_progress' | 'completed' | 'blocked';
+}
+/**
+ * Source reference for a plan (spec or constraint it derives from).
+ */
+export interface SourceReference {
+    /** Entity ID of the source */
+    readonly id: SpecId | ConstraintId;
+    /** Hash of the source at plan creation time */
+    readonly hash: Hash;
+}
+/**
+ * Plan captures implementation decisions derived from specs.
+ *
+ * @see req:entity:plan
+ */
+export interface Plan {
+    /** Unique id in format `plan:{name}:v{version}` */
+    readonly id: PlanId;
+    /** Semantic version */
+    readonly version: string;
+    /** Human-readable title */
+    readonly title: string;
+    /** Entity status */
+    readonly status: EntityStatus;
+    /** Specs and constraints this plan derives from */
+    readonly sources: readonly SourceReference[];
+    /** Decisions that resolve ambiguity in specs */
+    readonly decisions: readonly Decision[];
+    /** Ordered implementation steps */
+    readonly steps: readonly Step[];
+    /** Content hash (computed, not stored in YAML) */
+    readonly hash?: Hash;
+}
+/**
+ * File location for a trace (path with optional line range).
+ */
+export interface FileLocation {
+    /** Relative file path from project root */
+    readonly path: string;
+    /** Starting line number (1-indexed) */
+    readonly startLine?: number;
+    /** Ending line number (1-indexed, inclusive) */
+    readonly endLine?: number;
+}
+/**
+ * Trace links implementation artifacts to their provenance.
+ *
+ * @see req:entity:trace
+ */
+export interface Trace {
+    /** Unique id in format `trace:{hash}` */
+    readonly id: TraceId;
+    /** File location of the artifact */
+    readonly artifact: FileLocation;
+    /** Plan step this artifact implements */
+    readonly step: StepId;
+    /** Content hash of the artifact at trace time */
+    readonly artifactHash: Hash;
+    /** Timestamp when trace was created */
+    readonly createdAt: Timestamp;
+    /** Whether the trace is stale (artifact changed since trace) */
+    readonly stale?: boolean;
+}
+/**
+ * Node types in the intent graph.
+ */
+export type NodeType = 'spec' | 'requirement' | 'constraint' | 'invariant' | 'plan' | 'decision' | 'step' | 'artifact';
+/**
+ * Edge types in the intent graph.
+ */
+export type EdgeType = 'contains' | 'derives_from' | 'traces_to' | 'implements' | 'depends_on';
+/**
+ * A node in the intent graph.
+ */
+export interface GraphNode {
+    readonly id: EntityId;
+    readonly type: NodeType;
+    readonly hash?: Hash;
+    readonly data: Spec | Requirement | Constraint | Invariant | Plan | Decision | Step | Trace;
+}
+/**
+ * An edge in the intent graph.
+ */
+export interface GraphEdge {
+    readonly from: EntityId;
+    readonly to: EntityId;
+    readonly type: EdgeType;
+}
+/**
+ * The complete intent graph.
+ */
+export interface IntentGraph {
+    readonly nodes: ReadonlyMap<EntityId, GraphNode>;
+    readonly edges: readonly GraphEdge[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Core type definitions for prov entities.
+ *
+ * These types represent the fundamental entities in the intent graph:
+ * specifications, constraints, plans, decisions, steps, and traces.
+ *
+ * All entities are content-addressable via SHA-256 hash.
+ *
+ * @see spec:core-model:v1
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/types.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.test.d.ts.map

package/dist/types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.d.ts","sourceRoot":"","sources":["../src/types.test.ts"],"names":[],"mappings":""}

package/dist/types.test.js

@@ -0,0 +1,232 @@
+import { describe, it, expect } from 'vitest';
+describe('Type definitions', () => {
+    describe('ID formats', () => {
+        it('SpecId follows spec:{name}:v{version} format', () => {
+            const id = 'spec:core-model:v1';
+            expect(id).toMatch(/^spec:[a-z0-9-]+:v\d+$/);
+        });
+        it('RequirementId follows req:{spec}:{name} format', () => {
+            const id = 'req:core-model:entity-spec';
+            expect(id).toMatch(/^req:[a-z0-9-]+:[a-z0-9-]+$/);
+        });
+        it('ConstraintId follows constraint:{name}:v{version} format', () => {
+            const id = 'constraint:code-quality:v1';
+            expect(id).toMatch(/^constraint:[a-z0-9-]+:v\d+$/);
+        });
+        it('InvariantId follows inv:{constraint}:{name} format', () => {
+            const id = 'inv:code-quality:no-any';
+            expect(id).toMatch(/^inv:[a-z0-9-]+:[a-z0-9-]+$/);
+        });
+        it('PlanId follows plan:{name}:v{version} format', () => {
+            const id = 'plan:bootstrap:v1';
+            expect(id).toMatch(/^plan:[a-z0-9-]+:v\d+$/);
+        });
+        it('DecisionId follows dec:{plan}:{name} format', () => {
+            const id = 'dec:bootstrap:storage-format';
+            expect(id).toMatch(/^dec:[a-z0-9-]+:[a-z0-9-]+$/);
+        });
+        it('StepId follows step:{plan}:{number} format', () => {
+            const id = 'step:bootstrap:1';
+            expect(id).toMatch(/^step:[a-z0-9-]+:\d+$/);
+        });
+        it('TraceId follows trace:{hash} format', () => {
+            const id = 'trace:abc123def456';
+            expect(id).toMatch(/^trace:[a-z0-9]+$/);
+        });
+    });
+    describe('Hash format', () => {
+        it('Hash follows sha256:{12-hex-chars} format', () => {
+            const hash = 'sha256:a1b2c3d4e5f6';
+            expect(hash).toMatch(/^sha256:[a-f0-9]+$/);
+        });
+    });
+    describe('Spec entity', () => {
+        it('can be constructed with required fields', () => {
+            const spec = {
+                id: 'spec:test:v1',
+                version: '1.0.0',
+                title: 'Test Specification',
+                status: 'draft',
+                intent: 'Test intent description',
+                requirements: [
+                    {
+                        id: 'req:test:first',
+                        description: 'First requirement',
+                        acceptance: ['Acceptance criterion 1'],
+                    },
+                ],
+            };
+            expect(spec.id).toBe('spec:test:v1');
+            expect(spec.requirements).toHaveLength(1);
+        });
+        it('supports optional hash field', () => {
+            const spec = {
+                id: 'spec:test:v1',
+                version: '1.0.0',
+                title: 'Test Specification',
+                status: 'active',
+                intent: 'Test intent',
+                requirements: [],
+                hash: 'sha256:abc123def456',
+            };
+            expect(spec.hash).toBe('sha256:abc123def456');
+        });
+    });
+    describe('Requirement entity', () => {
+        it('can have string acceptance criteria', () => {
+            const req = {
+                id: 'req:test:simple',
+                description: 'Simple requirement',
+                acceptance: ['Criterion 1', 'Criterion 2'],
+            };
+            expect(req.acceptance).toHaveLength(2);
+        });
+        it('can have structured acceptance criteria', () => {
+            const req = {
+                id: 'req:test:structured',
+                description: 'Structured requirement',
+                acceptance: [
+                    {
+                        description: 'Criterion with verification',
+                        verification: 'npm run test',
+                    },
+                ],
+            };
+            expect(req.acceptance[0]).toHaveProperty('verification');
+        });
+        it('can have dependencies on other requirements', () => {
+            const req = {
+                id: 'req:test:dependent',
+                description: 'Dependent requirement',
+                acceptance: ['Criterion'],
+                dependencies: ['req:test:base'],
+            };
+            expect(req.dependencies).toContain('req:test:base');
+        });
+    });
+    describe('Constraint entity', () => {
+        it('contains invariants with verification methods', () => {
+            const constraint = {
+                id: 'constraint:quality:v1',
+                version: '1.0.0',
+                title: 'Code Quality',
+                status: 'active',
+                description: 'Ensures code quality standards',
+                invariants: [
+                    {
+                        id: 'inv:quality:no-any',
+                        rule: 'No use of any type',
+                        verification: {
+                            type: 'command',
+                            value: 'npm run typecheck',
+                            expect: 'success',
+                        },
+                        blocking: true,
+                    },
+                ],
+            };
+            expect(constraint.invariants[0]?.verification.type).toBe('command');
+        });
+    });
+    describe('Plan entity', () => {
+        it('references source specs/constraints with hashes', () => {
+            const plan = {
+                id: 'plan:impl:v1',
+                version: '1.0.0',
+                title: 'Implementation Plan',
+                status: 'active',
+                sources: [
+                    { id: 'spec:core:v1', hash: 'sha256:abc123def456' },
+                    { id: 'constraint:quality:v1', hash: 'sha256:789xyz123456' },
+                ],
+                decisions: [],
+                steps: [],
+            };
+            expect(plan.sources).toHaveLength(2);
+        });
+        it('contains decisions and steps', () => {
+            const plan = {
+                id: 'plan:impl:v1',
+                version: '1.0.0',
+                title: 'Implementation Plan',
+                status: 'active',
+                sources: [],
+                decisions: [
+                    {
+                        id: 'dec:impl:format',
+                        question: 'What format for storage?',
+                        choice: 'YAML',
+                        rationale: 'Human readable',
+                        tracesTo: ['req:core:storage'],
+                    },
+                ],
+                steps: [
+                    {
+                        id: 'step:impl:1',
+                        number: 1,
+                        action: 'Create storage module',
+                        tracesTo: ['dec:impl:format'],
+                        status: 'pending',
+                    },
+                ],
+            };
+            expect(plan.decisions).toHaveLength(1);
+            expect(plan.steps).toHaveLength(1);
+        });
+    });
+    describe('Trace entity', () => {
+        it('links artifacts to steps with hash tracking', () => {
+            const trace = {
+                id: 'trace:abc123',
+                artifact: {
+                    path: 'src/storage.ts',
+                    startLine: 10,
+                    endLine: 50,
+                },
+                step: 'step:impl:1',
+                artifactHash: 'sha256:def456abc123',
+                createdAt: '2024-01-01T00:00:00Z',
+            };
+            expect(trace.artifact.path).toBe('src/storage.ts');
+            expect(trace.artifactHash).toMatch(/^sha256:/);
+        });
+        it('can be marked as stale', () => {
+            const trace = {
+                id: 'trace:xyz789',
+                artifact: { path: 'src/modified.ts' },
+                step: 'step:impl:2',
+                artifactHash: 'sha256:old123hash456',
+                createdAt: '2024-01-01T00:00:00Z',
+                stale: true,
+            };
+            expect(trace.stale).toBe(true);
+        });
+    });
+    describe('Graph types', () => {
+        it('GraphNode wraps entities with type info', () => {
+            const node = {
+                id: 'spec:test:v1',
+                type: 'spec',
+                hash: 'sha256:abc123def456',
+                data: {
+                    id: 'spec:test:v1',
+                    version: '1.0.0',
+                    title: 'Test',
+                    status: 'draft',
+                    intent: 'Test',
+                    requirements: [],
+                },
+            };
+            expect(node.type).toBe('spec');
+        });
+        it('GraphEdge connects nodes with relationship type', () => {
+            const edge = {
+                from: 'spec:test:v1',
+                to: 'req:test:first',
+                type: 'contains',
+            };
+            expect(edge.type).toBe('contains');
+        });
+    });
+});
+//# sourceMappingURL=types.test.js.map

package/dist/types.test.js.map

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