@dedesfr/prompter 0.6.14 → 0.7.0

package/src/core/artifact-graph/graph.ts

@@ -0,0 +1,167 @@
+import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './types.js';
+import { loadSchema, parseSchema } from './schema.js';
+
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export class ArtifactGraph {
+  private artifacts: Map<string, Artifact>;
+  private schema: SchemaYaml;
+
+  private constructor(schema: SchemaYaml) {
+    this.schema = schema;
+    this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+  }
+
+  /**
+   * Creates an ArtifactGraph from a YAML file path.
+   */
+  static fromYaml(filePath: string): ArtifactGraph {
+    const schema = loadSchema(filePath);
+    return new ArtifactGraph(schema);
+  }
+
+  /**
+   * Creates an ArtifactGraph from YAML content string.
+   */
+  static fromYamlContent(yamlContent: string): ArtifactGraph {
+    const schema = parseSchema(yamlContent);
+    return new ArtifactGraph(schema);
+  }
+
+  /**
+   * Creates an ArtifactGraph from a pre-validated schema object.
+   */
+  static fromSchema(schema: SchemaYaml): ArtifactGraph {
+    return new ArtifactGraph(schema);
+  }
+
+  /**
+   * Gets a single artifact by ID.
+   */
+  getArtifact(id: string): Artifact | undefined {
+    return this.artifacts.get(id);
+  }
+
+  /**
+   * Gets all artifacts in the graph.
+   */
+  getAllArtifacts(): Artifact[] {
+    return Array.from(this.artifacts.values());
+  }
+
+  /**
+   * Gets the schema name.
+   */
+  getName(): string {
+    return this.schema.name;
+  }
+
+  /**
+   * Gets the schema version.
+   */
+  getVersion(): number {
+    return this.schema.version;
+  }
+
+  /**
+   * Computes the topological build order using Kahn's algorithm.
+   * Returns artifact IDs in the order they should be built.
+   */
+  getBuildOrder(): string[] {
+    const inDegree = new Map<string, number>();
+    const dependents = new Map<string, string[]>();
+
+    // Initialize all artifacts
+    for (const artifact of this.artifacts.values()) {
+      inDegree.set(artifact.id, artifact.requires.length);
+      dependents.set(artifact.id, []);
+    }
+
+    // Build reverse adjacency (who depends on whom)
+    for (const artifact of this.artifacts.values()) {
+      for (const req of artifact.requires) {
+        dependents.get(req)!.push(artifact.id);
+      }
+    }
+
+    // Start with roots (in-degree 0), sorted for determinism
+    const queue = [...this.artifacts.keys()]
+      .filter(id => inDegree.get(id) === 0)
+      .sort();
+
+    const result: string[] = [];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      result.push(current);
+
+      // Collect newly ready artifacts, then sort before adding
+      const newlyReady: string[] = [];
+      for (const dep of dependents.get(current)!) {
+        const newDegree = inDegree.get(dep)! - 1;
+        inDegree.set(dep, newDegree);
+        if (newDegree === 0) {
+          newlyReady.push(dep);
+        }
+      }
+      queue.push(...newlyReady.sort());
+    }
+
+    return result;
+  }
+
+  /**
+   * Gets artifacts that are ready to be created (all dependencies completed).
+   */
+  getNextArtifacts(completed: CompletedSet): string[] {
+    const ready: string[] = [];
+
+    for (const artifact of this.artifacts.values()) {
+      if (completed.has(artifact.id)) {
+        continue; // Already completed
+      }
+
+      const allDepsCompleted = artifact.requires.every(req => completed.has(req));
+      if (allDepsCompleted) {
+        ready.push(artifact.id);
+      }
+    }
+
+    // Sort for deterministic ordering
+    return ready.sort();
+  }
+
+  /**
+   * Checks if all artifacts in the graph are completed.
+   */
+  isComplete(completed: CompletedSet): boolean {
+    for (const artifact of this.artifacts.values()) {
+      if (!completed.has(artifact.id)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Gets blocked artifacts and their unmet dependencies.
+   */
+  getBlocked(completed: CompletedSet): BlockedArtifacts {
+    const blocked: BlockedArtifacts = {};
+
+    for (const artifact of this.artifacts.values()) {
+      if (completed.has(artifact.id)) {
+        continue; // Already completed
+      }
+
+      const unmetDeps = artifact.requires.filter(req => !completed.has(req));
+      if (unmetDeps.length > 0) {
+        blocked[artifact.id] = unmetDeps.sort();
+      }
+    }
+
+    return blocked;
+  }
+}

package/src/core/artifact-graph/index.ts

@@ -0,0 +1,44 @@
+// Types
+export {
+  ArtifactSchema,
+  SchemaYamlSchema,
+  type Artifact,
+  type SchemaYaml,
+  type CompletedSet,
+  type BlockedArtifacts,
+} from './types.js';
+
+// Schema loading and validation
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+
+// Graph operations
+export { ArtifactGraph } from './graph.js';
+
+// State detection
+export { detectCompleted } from './state.js';
+
+// Schema resolution
+export {
+  resolveSchema,
+  listSchemas,
+  listSchemasWithInfo,
+  getSchemaDir,
+  getPackageSchemasDir,
+  getUserSchemasDir,
+  SchemaLoadError,
+  type SchemaInfo,
+} from './resolver.js';
+
+// Instruction loading
+export {
+  loadTemplate,
+  loadChangeContext,
+  generateInstructions,
+  formatChangeStatus,
+  TemplateLoadError,
+  type ChangeContext,
+  type ArtifactInstructions,
+  type DependencyInfo,
+  type ArtifactStatus,
+  type ChangeStatus,
+} from './instruction-loader.js';

package/src/core/artifact-graph/instruction-loader.ts

@@ -0,0 +1,302 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getSchemaDir, resolveSchema } from './resolver.js';
+import { ArtifactGraph } from './graph.js';
+import { detectCompleted } from './state.js';
+import { resolveSchemaForChange } from '../../utils/change-metadata.js';
+import type { Artifact, CompletedSet } from './types.js';
+
+/**
+ * Error thrown when loading a template fails.
+ */
+export class TemplateLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly templatePath: string
+  ) {
+    super(message);
+    this.name = 'TemplateLoadError';
+  }
+}
+
+/**
+ * Change context containing graph, completion state, and metadata.
+ */
+export interface ChangeContext {
+  /** The artifact dependency graph */
+  graph: ArtifactGraph;
+  /** Set of completed artifact IDs */
+  completed: CompletedSet;
+  /** Schema name being used */
+  schemaName: string;
+  /** Change name */
+  changeName: string;
+  /** Path to the change directory */
+  changeDir: string;
+}
+
+/**
+ * Enriched instructions for creating an artifact.
+ */
+export interface ArtifactInstructions {
+  /** Change name */
+  changeName: string;
+  /** Artifact ID */
+  artifactId: string;
+  /** Schema name */
+  schemaName: string;
+  /** Full path to change directory */
+  changeDir: string;
+  /** Output path pattern (e.g., "proposal.md") */
+  outputPath: string;
+  /** Artifact description */
+  description: string;
+  /** Guidance on how to create this artifact (from schema instruction field) */
+  instruction: string | undefined;
+  /** Template content (structure to follow) */
+  template: string;
+  /** Dependencies with completion status and paths */
+  dependencies: DependencyInfo[];
+  /** Artifacts that become available after completing this one */
+  unlocks: string[];
+}
+
+/**
+ * Dependency information including path and description.
+ */
+export interface DependencyInfo {
+  /** Artifact ID */
+  id: string;
+  /** Whether the dependency is completed */
+  done: boolean;
+  /** Relative output path of the dependency (e.g., "proposal.md") */
+  path: string;
+  /** Description of the dependency artifact */
+  description: string;
+}
+
+/**
+ * Status of a single artifact in the workflow.
+ */
+export interface ArtifactStatus {
+  /** Artifact ID */
+  id: string;
+  /** Output path pattern */
+  outputPath: string;
+  /** Status: done, ready, or blocked */
+  status: 'done' | 'ready' | 'blocked';
+  /** Missing dependencies (only for blocked) */
+  missingDeps?: string[];
+}
+
+/**
+ * Formatted change status.
+ */
+export interface ChangeStatus {
+  /** Change name */
+  changeName: string;
+  /** Schema name */
+  schemaName: string;
+  /** Whether all artifacts are complete */
+  isComplete: boolean;
+  /** Artifact IDs required before apply phase (from schema's apply.requires) */
+  applyRequires: string[];
+  /** Status of each artifact */
+  artifacts: ArtifactStatus[];
+}
+
+/**
+ * Loads a template from a schema's templates directory.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export function loadTemplate(schemaName: string, templatePath: string): string {
+  const schemaDir = getSchemaDir(schemaName);
+  if (!schemaDir) {
+    throw new TemplateLoadError(
+      `Schema '${schemaName}' not found`,
+      templatePath
+    );
+  }
+
+  const fullPath = path.join(schemaDir, 'templates', templatePath);
+
+  if (!fs.existsSync(fullPath)) {
+    throw new TemplateLoadError(
+      `Template not found: ${fullPath}`,
+      fullPath
+    );
+  }
+
+  try {
+    return fs.readFileSync(fullPath, 'utf-8');
+  } catch (err) {
+    const ioError = err instanceof Error ? err : new Error(String(err));
+    throw new TemplateLoadError(
+      `Failed to read template: ${ioError.message}`,
+      fullPath
+    );
+  }
+}
+
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * Schema resolution order:
+ * 1. Explicit schemaName parameter (if provided)
+ * 2. Schema from .prompter.yaml metadata (if exists in change directory)
+ * 3. Default 'spec-driven'
+ *
+ * @param projectRoot - Project root directory
+ * @param changeName - Change name
+ * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
+ * @returns Change context with graph, completed set, and metadata
+ */
+export function loadChangeContext(
+  projectRoot: string,
+  changeName: string,
+  schemaName?: string
+): ChangeContext {
+  const changeDir = path.join(projectRoot, 'prompter', 'changes', changeName);
+
+  // Resolve schema: explicit > metadata > default
+  const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);
+
+  const schema = resolveSchema(resolvedSchemaName);
+  const graph = ArtifactGraph.fromSchema(schema);
+  const completed = detectCompleted(graph, changeDir);
+
+  return {
+    graph,
+    completed,
+    schemaName: resolvedSchemaName,
+    changeName,
+    changeDir,
+  };
+}
+
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export function generateInstructions(
+  context: ChangeContext,
+  artifactId: string
+): ArtifactInstructions {
+  const artifact = context.graph.getArtifact(artifactId);
+  if (!artifact) {
+    throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
+  }
+
+  const template = loadTemplate(context.schemaName, artifact.template);
+  const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
+  const unlocks = getUnlockedArtifacts(context.graph, artifactId);
+
+  return {
+    changeName: context.changeName,
+    artifactId: artifact.id,
+    schemaName: context.schemaName,
+    changeDir: context.changeDir,
+    outputPath: artifact.generates,
+    description: artifact.description,
+    instruction: artifact.instruction,
+    template,
+    dependencies,
+    unlocks,
+  };
+}
+
+/**
+ * Gets dependency info including paths and descriptions.
+ */
+function getDependencyInfo(
+  artifact: Artifact,
+  graph: ArtifactGraph,
+  completed: CompletedSet
+): DependencyInfo[] {
+  return artifact.requires.map(id => {
+    const depArtifact = graph.getArtifact(id);
+    return {
+      id,
+      done: completed.has(id),
+      path: depArtifact?.generates ?? id,
+      description: depArtifact?.description ?? '',
+    };
+  });
+}
+
+/**
+ * Gets artifacts that become available after completing the given artifact.
+ */
+function getUnlockedArtifacts(graph: ArtifactGraph, artifactId: string): string[] {
+  const unlocks: string[] = [];
+
+  for (const artifact of graph.getAllArtifacts()) {
+    if (artifact.requires.includes(artifactId)) {
+      unlocks.push(artifact.id);
+    }
+  }
+
+  return unlocks.sort();
+}
+
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export function formatChangeStatus(context: ChangeContext): ChangeStatus {
+  // Load schema to get apply phase configuration
+  const schema = resolveSchema(context.schemaName);
+  const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
+
+  const artifacts = context.graph.getAllArtifacts();
+  const ready = new Set(context.graph.getNextArtifacts(context.completed));
+  const blocked = context.graph.getBlocked(context.completed);
+
+  const artifactStatuses: ArtifactStatus[] = artifacts.map(artifact => {
+    if (context.completed.has(artifact.id)) {
+      return {
+        id: artifact.id,
+        outputPath: artifact.generates,
+        status: 'done' as const,
+      };
+    }
+
+    if (ready.has(artifact.id)) {
+      return {
+        id: artifact.id,
+        outputPath: artifact.generates,
+        status: 'ready' as const,
+      };
+    }
+
+    return {
+      id: artifact.id,
+      outputPath: artifact.generates,
+      status: 'blocked' as const,
+      missingDeps: blocked[artifact.id] ?? [],
+    };
+  });
+
+  // Sort by build order for consistent output
+  const buildOrder = context.graph.getBuildOrder();
+  const orderMap = new Map(buildOrder.map((id, idx) => [id, idx]));
+  artifactStatuses.sort((a, b) => (orderMap.get(a.id) ?? 0) - (orderMap.get(b.id) ?? 0));
+
+  return {
+    changeName: context.changeName,
+    schemaName: context.schemaName,
+    isComplete: context.graph.isComplete(context.completed),
+    applyRequires,
+    artifacts: artifactStatuses,
+  };
+}