@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/artifact-graph/graph.d.ts

@@ -0,0 +1,72 @@
+import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './types.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export declare class ArtifactGraph {
+    private artifacts;
+    private schema;
+    /** Artifact id -> its position in the schema's `artifacts:` list. */
+    private declarationOrder;
+    private constructor();
+    /**
+     * Orders artifact ids by where the schema declares them.
+     *
+     * The dependency graph leaves siblings tied - spec-driven's `specs` and
+     * `design` both require only `proposal`, so both become ready at the same
+     * time. Ties used to be broken alphabetically, which put `design` ahead of
+     * `specs` and made the CLI recommend the artifacts in an order that
+     * contradicted the schema's own documented sequence
+     * (proposal -> specs -> design -> tasks). Breaking ties by declaration order
+     * follows the sequence the schema author wrote, for built-in and custom
+     * schemas alike, and stays just as deterministic. Ids not in the schema sort
+     * last so the comparator stays total.
+     */
+    private compareByDeclarationOrder;
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema: SchemaYaml): ArtifactGraph;
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id: string): Artifact | undefined;
+    /**
+     * Gets all artifacts in the graph.
+     */
+    getAllArtifacts(): Artifact[];
+    /**
+     * Gets the schema name.
+     */
+    getName(): string;
+    /**
+     * Gets the schema version.
+     */
+    getVersion(): number;
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder(): string[];
+    /**
+     * Gets artifacts that are ready to be created (all dependencies completed).
+     */
+    getNextArtifacts(completed: CompletedSet): string[];
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed: CompletedSet): boolean;
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     */
+    getBlocked(completed: CompletedSet): BlockedArtifacts;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/core/artifact-graph/graph.js

@@ -0,0 +1,165 @@
+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 {
+    artifacts;
+    schema;
+    /** Artifact id -> its position in the schema's `artifacts:` list. */
+    declarationOrder;
+    constructor(schema) {
+        this.schema = schema;
+        this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+        this.declarationOrder = new Map(schema.artifacts.map((a, index) => [a.id, index]));
+    }
+    /**
+     * Orders artifact ids by where the schema declares them.
+     *
+     * The dependency graph leaves siblings tied - spec-driven's `specs` and
+     * `design` both require only `proposal`, so both become ready at the same
+     * time. Ties used to be broken alphabetically, which put `design` ahead of
+     * `specs` and made the CLI recommend the artifacts in an order that
+     * contradicted the schema's own documented sequence
+     * (proposal -> specs -> design -> tasks). Breaking ties by declaration order
+     * follows the sequence the schema author wrote, for built-in and custom
+     * schemas alike, and stays just as deterministic. Ids not in the schema sort
+     * last so the comparator stays total.
+     */
+    compareByDeclarationOrder(a, b) {
+        return ((this.declarationOrder.get(a) ?? Number.MAX_SAFE_INTEGER) -
+            (this.declarationOrder.get(b) ?? Number.MAX_SAFE_INTEGER));
+    }
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath) {
+        const schema = loadSchema(filePath);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent) {
+        const schema = parseSchema(yamlContent);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema) {
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id) {
+        return this.artifacts.get(id);
+    }
+    /**
+     * Gets all artifacts in the graph.
+     */
+    getAllArtifacts() {
+        return Array.from(this.artifacts.values());
+    }
+    /**
+     * Gets the schema name.
+     */
+    getName() {
+        return this.schema.name;
+    }
+    /**
+     * Gets the schema version.
+     */
+    getVersion() {
+        return this.schema.version;
+    }
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder() {
+        const inDegree = new Map();
+        const dependents = new Map();
+        // 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), in declaration order for determinism
+        const queue = [...this.artifacts.keys()]
+            .filter(id => inDegree.get(id) === 0)
+            .sort((a, b) => this.compareByDeclarationOrder(a, b));
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(current);
+            // Collect newly ready artifacts, then sort before adding
+            const newlyReady = [];
+            for (const dep of dependents.get(current)) {
+                const newDegree = inDegree.get(dep) - 1;
+                inDegree.set(dep, newDegree);
+                if (newDegree === 0) {
+                    newlyReady.push(dep);
+                }
+            }
+            // Re-sort the whole queue, not just the new arrivals: an artifact that
+            // has been waiting can be declared after one that just became ready.
+            queue.push(...newlyReady);
+            queue.sort((a, b) => this.compareByDeclarationOrder(a, b));
+        }
+        return result;
+    }
+    /**
+     * Gets artifacts that are ready to be created (all dependencies completed).
+     */
+    getNextArtifacts(completed) {
+        const ready = [];
+        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);
+            }
+        }
+        // Declaration order: deterministic, and the first entry is the artifact the
+        // schema wants written next.
+        return ready.sort((a, b) => this.compareByDeclarationOrder(a, b));
+    }
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed) {
+        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) {
+        const blocked = {};
+        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((a, b) => this.compareByDeclarationOrder(a, b));
+            }
+        }
+        return blocked;
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/core/artifact-graph/index.d.ts

@@ -0,0 +1,9 @@
+export { ArtifactSchema, SchemaYamlSchema, type Artifact, type SchemaYaml, type CompletedSet, type BlockedArtifacts, } from './types.js';
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+export { ArtifactGraph } from './graph.js';
+export { detectCompleted } from './state.js';
+export { artifactOutputExists, isGlobPattern, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
+export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, type SchemaInfo, } from './resolver.js';
+export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, type ChangeContext, type LoadChangeContextOptions, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, type ArtifactPathSummary, } from './instruction-loader.js';
+export type { PlanningHomeSummary, ActionContext, } from '../change-status-policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/artifact-graph/index.js

@@ -0,0 +1,14 @@
+// Types
+export { ArtifactSchema, SchemaYamlSchema, } 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';
+export { artifactOutputExists, isGlobPattern, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
+// Schema resolution
+export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, } from './resolver.js';
+// Instruction loading
+export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, } from './instruction-loader.js';
+//# sourceMappingURL=index.js.map

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -0,0 +1,208 @@
+import { ArtifactGraph } from './graph.js';
+import { type ActionContext, type PlanningHomeSummary } from '../change-status-policy.js';
+import { type ProjectConfig } from '../project-config.js';
+import type { PlanningHome } from '../planning-home.js';
+import type { ChangeMetadata } from '../change-metadata/index.js';
+import type { CompletedSet } from './types.js';
+/**
+ * Error thrown when loading a template fails.
+ */
+export declare class TemplateLoadError extends Error {
+    readonly templatePath: string;
+    constructor(message: string, templatePath: string);
+}
+/**
+ * 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;
+    /** Project root directory */
+    projectRoot: string;
+    /** Resolved planning home for this change */
+    planningHome?: PlanningHome;
+    /** Parsed change metadata, when present */
+    metadata?: ChangeMetadata;
+    /** Non-fatal metadata diagnostics for text and JSON command surfaces */
+    warnings?: string[];
+    /**
+     * Artifact IDs counted as complete only because the change declares
+     * skip_specs, not because their files exist. Kept separate so status can
+     * render them as skipped rather than done.
+     */
+    skippedArtifacts?: Set<string>;
+}
+export interface LoadChangeContextOptions {
+    changeDir?: string;
+    planningHome?: PlanningHome;
+    /** Pre-read project config; suppresses schema resolution's fallback config read. */
+    projectConfig?: ProjectConfig | null;
+}
+/**
+ * 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;
+    /** Resolved planning home for this change */
+    planningHome?: PlanningHomeSummary;
+    /** Output path pattern (e.g., "proposal.md") */
+    outputPath: string;
+    /** Absolute output path or glob pattern resolved under the change directory */
+    resolvedOutputPath: string;
+    /** Existing concrete output files for this artifact */
+    existingOutputPaths: string[];
+    /** Artifact description */
+    description: string;
+    /** Guidance on how to create this artifact (from schema instruction field) */
+    instruction: string | undefined;
+    /** Project context from config (constraints/background for AI, not to be included in output) */
+    context: string | undefined;
+    /** Artifact-specific rules from config (constraints for AI, not to be included in output) */
+    rules: string[] | undefined;
+    /** Template content (structure to follow - this IS the output format) */
+    template: string;
+    /** Dependencies with completion status and paths */
+    dependencies: DependencyInfo[];
+    /** Artifacts that become available after completing this one */
+    unlocks: string[];
+    /** True when the change declares skip_specs and this artifact is skipped */
+    skipped?: boolean;
+    /** Present only when skipped: tells the consumer not to create the artifact */
+    warning?: string;
+    /** Non-fatal metadata diagnostics */
+    warnings?: 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;
+    /** True when the dependency is satisfied via skip_specs - no files exist to read */
+    skipped?: boolean;
+}
+/**
+ * Status of a single artifact in the workflow.
+ */
+export interface ArtifactStatus {
+    /** Artifact ID */
+    id: string;
+    /** Output path pattern */
+    outputPath: string;
+    /** Status: done, skipped (via skip_specs), ready, or blocked */
+    status: 'done' | 'skipped' | 'ready' | 'blocked';
+    /** Artifact IDs this artifact directly requires (its `requires` edges).
+     * Present for every status so callers can compute the transitive required
+     * set even when the artifact is already `done` (file-existence status does
+     * not imply its dependencies exist). */
+    requires: string[];
+    /** Missing dependencies (only for blocked) */
+    missingDeps?: string[];
+}
+/**
+ * Formatted change status.
+ */
+export interface ChangeStatus {
+    /** Change name */
+    changeName: string;
+    /** Schema name */
+    schemaName: string;
+    /** Planning home facts (generated skills derive the archive dir
+     * from planningHome.changesDir - a published agent contract). */
+    planningHome?: PlanningHomeSummary;
+    /** Full path to the change root */
+    changeRoot: string;
+    /** Absolute artifact path details keyed by artifact ID */
+    artifactPaths: Record<string, ArtifactPathSummary>;
+    /** Plain-language next steps for users and agents */
+    nextSteps: string[];
+    /** Machine-readable action constraints for agents */
+    actionContext: ActionContext;
+    /** Whether all planning artifacts are complete */
+    isPlanningComplete: boolean;
+    /** Compatibility alias for isPlanningComplete */
+    isComplete: boolean;
+    /** Artifact IDs required before apply phase (from schema's apply.requires) */
+    applyRequires: string[];
+    /** Status of each artifact */
+    artifacts: ArtifactStatus[];
+    /** Non-fatal metadata diagnostics */
+    warnings?: string[];
+}
+export interface ArtifactPathSummary {
+    outputPath: string;
+    resolvedOutputPath: string;
+    existingOutputPaths: string[];
+}
+/**
+ * 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")
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export declare function loadTemplate(schemaName: string, templatePath: string, projectRoot?: string): string;
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * Schema resolution order:
+ * 1. Explicit schemaName parameter (if provided)
+ * 2. Schema from .freespec.yaml metadata (if exists in change directory)
+ * 3. Default schema (`默认`)
+ *
+ * @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 declare function loadChangeContext(projectRoot: string, changeName: string, schemaName?: string, options?: LoadChangeContextOptions): ChangeContext;
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * Instruction injection order:
+ * 1. <context> - Project context from config (if present)
+ * 2. <rules> - Artifact-specific rules from config (if present)
+ * 3. <template> - Schema's template content
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @param projectRoot - Project root directory (for reading config)
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export interface GenerateInstructionsOptions {
+    /** Pre-read project config; suppresses the internal read (no double read). */
+    projectConfig?: ProjectConfig | null;
+}
+export declare function generateInstructions(context: ChangeContext, artifactId: string, projectRoot?: string, options?: GenerateInstructionsOptions): ArtifactInstructions;
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export declare function formatChangeStatus(context: ChangeContext): ChangeStatus;
+//# sourceMappingURL=instruction-loader.d.ts.map