@caiqueoak/flow 0.3.3 → 0.5.0

package/src/artifacts/backlog.mjs

@@ -0,0 +1,162 @@
+import { parseDocument } from 'yaml';
+
+export class ArtifactValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ArtifactValidationError';
+  }
+}
+
+const KINDS = new Set(['feature', 'technical', 'maintenance']);
+const STATES = new Set(['pending', 'in_progress', 'completed']);
+const WORK_ITEM_ID = /^W\d{3,}$/;
+const WORK_ITEM_FOLDER = /^W\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function fail(message) {
+  throw new ArtifactValidationError(message);
+}
+
+function requireObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${label} must be a mapping.`);
+  return value;
+}
+
+function requireString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) fail(`${label} must be a non-empty string.`);
+  return value.trim();
+}
+
+export function parseBacklog(text, { source = 'backlog.yaml' } = {}) {
+  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length) fail(`${source} is invalid: ${document.errors[0].message}`);
+  const backlog = requireObject(document.toJS(), source);
+  if (backlog.schema_version !== 2) fail(`${source} schema_version must be 2.`);
+  if (!Array.isArray(backlog.work_items)) fail(`${source} work_items must be a list.`);
+
+  const ids = new Set();
+  const items = backlog.work_items.map((raw, index) => {
+    const label = `work_items[${index}]`;
+    const item = requireObject(raw, label);
+    const id = requireString(item.id, `${label}.id`);
+    if (!WORK_ITEM_ID.test(id)) fail(`${label}.id must use W followed by a zero-padded numeric sequence, e.g. W015.`);
+    if (ids.has(id)) fail(`${source} contains duplicate work-item ID '${id}'.`);
+    ids.add(id);
+
+    const folder = requireString(item.folder ?? item.path, `${label}.folder`);
+    if (!WORK_ITEM_FOLDER.test(folder))
+      fail(`${label}.folder must use W###-kebab-case, e.g. W015-learner-web-application.`);
+    const numericId = id.slice(1);
+    if (!folder.startsWith(`W${numericId}-`)) fail(`${label}.folder must preserve the numeric sequence from ${id}.`);
+
+    if (!KINDS.has(item.kind)) fail(`${label}.kind must be feature, technical, or maintenance.`);
+    const title = requireString(item.title, `${label}.title`);
+    const state = item.state ?? item.status;
+    if (!STATES.has(state)) fail(`${label}.state must be pending, in_progress, or completed.`);
+    if (!Number.isInteger(item.priority) || item.priority < 1) fail(`${label}.priority must be a positive integer.`);
+    if (!Array.isArray(item.depends_on ?? [])) fail(`${label}.depends_on must be a list.`);
+    if (!Array.isArray(item.blockers ?? [])) fail(`${label}.blockers must be a list when present.`);
+
+    const dependencies = [];
+    const seenDependencies = new Set();
+    for (const rawDependency of item.depends_on ?? []) {
+      const dependency = requireString(rawDependency, `${label}.depends_on entry`);
+      if (!WORK_ITEM_ID.test(dependency)) fail(`${label}.depends_on contains invalid work-item ID '${dependency}'.`);
+      if (dependency === id) fail(`Work item '${id}' cannot depend on itself.`);
+      if (seenDependencies.has(dependency)) fail(`Work item '${id}' lists dependency '${dependency}' more than once.`);
+      seenDependencies.add(dependency);
+      dependencies.push(dependency);
+    }
+
+    return {
+      id,
+      folder,
+      kind: item.kind,
+      title,
+      state,
+      priority: item.priority,
+      depends_on: dependencies,
+      blockers: (item.blockers ?? []).map((blocker) => {
+        requireObject(blocker, `${id} blocker`);
+        if (!/^[a-z][a-z0-9-]*$/.test(blocker.id ?? '')) fail(`${id} blocker.id must be stable kebab-case.`);
+        if (!['external_action', 'consequential_decision'].includes(blocker.type))
+          fail(`${id} blocker.type is invalid.`);
+        requireString(blocker.description, `${id} blocker.description`);
+        if (!['unresolved', 'resolved'].includes(blocker.status)) fail(`${id} blocker.status is invalid.`);
+        return blocker;
+      })
+    };
+  });
+
+  const byId = new Map(items.map((item) => [item.id, item]));
+  for (const item of items) {
+    for (const dependency of item.depends_on) {
+      if (!byId.has(dependency)) fail(`Work item '${item.id}' depends on unknown work item '${dependency}'.`);
+    }
+  }
+  validateAcyclic(items);
+  if (items.filter((item) => item.state === 'in_progress').length > 1)
+    fail('Only one mutating work item may be in_progress.');
+  return { schema_version: 2, work_items: items };
+}
+
+export function validateAcyclic(items) {
+  const indegree = new Map(items.map((item) => [item.id, item.depends_on.length]));
+  const dependents = new Map(items.map((item) => [item.id, []]));
+  for (const item of items) for (const dependency of item.depends_on) dependents.get(dependency).push(item.id);
+  const queue = items.filter((item) => indegree.get(item.id) === 0).map((item) => item.id);
+  let visited = 0;
+  while (queue.length) {
+    const id = queue.shift();
+    visited += 1;
+    for (const dependent of dependents.get(id)) {
+      const next = indegree.get(dependent) - 1;
+      indegree.set(dependent, next);
+      if (next === 0) queue.push(dependent);
+    }
+  }
+  if (visited !== items.length) fail('backlog.yaml work-item dependencies contain a cycle.');
+}
+
+export function deriveExecutionStatus(item, byId) {
+  if (item.state === 'completed') return { status: 'completed', reasons: [] };
+  const incompleteDependencies = item.depends_on.filter((id) => byId.get(id)?.state !== 'completed');
+  const explicitBlockers = (item.blockers ?? []).filter((blocker) => blocker.status !== 'resolved');
+  if (incompleteDependencies.length || explicitBlockers.length) {
+    return {
+      status: 'blocked',
+      reasons: [...incompleteDependencies.map((id) => ({ type: 'dependency', ref: id })), ...explicitBlockers]
+    };
+  }
+  return { status: item.state === 'in_progress' ? 'in_progress' : 'ready', reasons: [] };
+}
+
+export function topologicalOrder(items) {
+  const byId = new Map(items.map((item) => [item.id, item]));
+  const remaining = new Map(items.map((item) => [item.id, item.depends_on.length]));
+  const dependents = new Map(items.map((item) => [item.id, []]));
+  for (const item of items) for (const dependency of item.depends_on) dependents.get(dependency).push(item.id);
+  const compare = (a, b) => a.localeCompare(b);
+  for (const ids of dependents.values()) ids.sort(compare);
+  const ready = items
+    .filter((item) => item.depends_on.length === 0)
+    .map((item) => item.id)
+    .sort(compare);
+  const levels = new Map(ready.map((id) => [id, 0]));
+  const orderedIds = [];
+  while (ready.length) {
+    const id = ready.shift();
+    orderedIds.push(id);
+    for (const dependent of dependents.get(id)) {
+      levels.set(dependent, Math.max(levels.get(dependent) ?? 0, (levels.get(id) ?? 0) + 1));
+      const count = remaining.get(dependent) - 1;
+      remaining.set(dependent, count);
+      if (count === 0) {
+        ready.push(dependent);
+        ready.sort(compare);
+      }
+    }
+  }
+  return orderedIds
+    .map((id) => byId.get(id))
+    .sort((a, b) => levels.get(a.id) - levels.get(b.id) || compare(a.id, b.id));
+}

package/src/artifacts/document.mjs

@@ -0,0 +1,30 @@
+import { parseDocument } from 'yaml';
+import { createHash } from 'node:crypto';
+export function documentRevision(text) {
+  return createHash('sha256').update(text).digest('hex');
+}
+export function documentMetadata(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error('Missing YAML frontmatter.');
+  const doc = parseDocument(match[1], { uniqueKeys: true });
+  if (doc.errors.length) throw new Error(doc.errors[0].message);
+  const value = doc.toJS();
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Frontmatter must be a mapping.');
+  return value;
+}
+export function validateDocument(text, headings) {
+  let metadata = {};
+  const errors = [];
+  try {
+    metadata = documentMetadata(text);
+  } catch (error) {
+    errors.push(error.message);
+  }
+  if (metadata.schema_version !== 1) errors.push('schema_version must be 1.');
+  if (!['draft', 'approved'].includes(metadata.status)) errors.push('status must be draft or approved.');
+  if (metadata.status === 'approved' && (!metadata.approved_at || Number.isNaN(Date.parse(metadata.approved_at))))
+    errors.push('approved_at must record the human approval timestamp.');
+  const actual = new Set(text.split(/\r?\n/).filter((line) => /^#{1,2} /.test(line)));
+  for (const heading of headings) if (!actual.has(heading)) errors.push(`Missing ${heading}.`);
+  return { ...metadata, errors };
+}

package/src/artifacts/engineering.mjs

@@ -0,0 +1,26 @@
+import { validateDocument } from './document.mjs';
+import { READABILITY_FIRST_PROFILE } from '../shared/profiles.mjs';
+export const ENGINEERING_HEADINGS = [
+  '# Engineering',
+  '## System shape',
+  '## Modules and ownership',
+  '## Dependency direction and boundaries',
+  '## Vertical slices and code organization',
+  '## Naming and readability conventions',
+  '## Data ownership and persistence',
+  '## Error handling',
+  '## Testing and verification',
+  '## Dependencies and external services',
+  '## Security and operations',
+  '## Deterministic gates',
+  '## Deferred complexity',
+  '## Exceptions'
+];
+export function validateEngineeringDocument(text) {
+  const result = validateDocument(text, ENGINEERING_HEADINGS);
+  if (result.baseline?.profile !== READABILITY_FIRST_PROFILE.id)
+    result.errors.push('baseline.profile must be flow/readability-first@1.');
+  if (!['improve', 'preserve', 'not_applicable'].includes(result.baseline?.existing_code_policy))
+    result.errors.push('baseline.existing_code_policy is invalid.');
+  return result;
+}

package/src/artifacts/gates.mjs

@@ -0,0 +1,28 @@
+import { parseDocument } from 'yaml';
+import { ArtifactValidationError } from './backlog.mjs';
+
+const KINDS = new Set(['command', 'builtin']);
+
+export function parseGates(text, { source = 'gates.yaml' } = {}) {
+  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length) throw new ArtifactValidationError(`${source} is invalid: ${document.errors[0].message}`);
+  const value = document.toJS();
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new ArtifactValidationError(`${source} must be a mapping.`);
+  if (value.schema_version !== 1) throw new ArtifactValidationError(`${source} schema_version must be 1.`);
+  if (!Array.isArray(value.gates)) throw new ArtifactValidationError(`${source} gates must be a list.`);
+  const ids = new Set();
+  const gates = value.gates.map((gate, index) => {
+    if (!gate || typeof gate !== 'object' || Array.isArray(gate))
+      throw new ArtifactValidationError(`gates[${index}] must be a mapping.`);
+    if (typeof gate.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(gate.id))
+      throw new ArtifactValidationError(`gates[${index}].id must be lower kebab-case.`);
+    if (ids.has(gate.id)) throw new ArtifactValidationError(`duplicate gate '${gate.id}'.`);
+    ids.add(gate.id);
+    if (!KINDS.has(gate.kind)) throw new ArtifactValidationError(`${gate.id}.kind must be command or builtin.`);
+    if (gate.kind === 'command' && (!gate.command || typeof gate.command !== 'string'))
+      throw new ArtifactValidationError(`${gate.id} command gate requires command.`);
+    return { ...gate, blocking: gate.blocking !== false };
+  });
+  return { schema_version: 1, gates };
+}

package/src/artifacts/implementation-plan.mjs

@@ -0,0 +1,27 @@
+import { documentRevision, validateDocument } from './document.mjs';
+export { documentRevision } from './document.mjs';
+export const PLAN_HEADINGS = [
+  '# Implementation Plan',
+  '## Outcome',
+  '## Current state',
+  '## Proposed changes',
+  '## Execution sequence',
+  '## Task mapping',
+  '## Data and control flow',
+  '## Engineering compliance',
+  '## Tests and validation',
+  '## Risks and rollback',
+  '## Deliberately excluded',
+  '## Human decisions required'
+];
+export function validateImplementationPlan(text, { workItem, engineeringText, specText, checkRevisions = true }) {
+  const result = validateDocument(text, PLAN_HEADINGS);
+  if (result.work_item !== workItem) result.errors.push('Plan belongs to a different work item.');
+  for (const key of ['engineering_revision', 'spec_revision'])
+    if (!/^[a-f0-9]{64}$/.test(result[key] ?? '')) result.errors.push(`${key} must be SHA256.`);
+  if (checkRevisions && result.engineering_revision !== documentRevision(engineeringText))
+    result.errors.push('Engineering revision is stale.');
+  if (checkRevisions && result.spec_revision !== documentRevision(specText))
+    result.errors.push('Spec revision is stale.');
+  return result;
+}

package/src/artifacts/prd.mjs

@@ -0,0 +1,12 @@
+import { validateDocument } from './document.mjs';
+export function validatePrdDocument(text) {
+  return validateDocument(text, [
+    '# Product Requirements',
+    '## Purpose',
+    '## Users',
+    '## Scope',
+    '## Requirements',
+    '## Constraints',
+    '## Non-goals'
+  ]);
+}

package/src/artifacts/state.mjs

@@ -0,0 +1,63 @@
+import { parseDocument, stringify } from 'yaml';
+import { ArtifactValidationError } from './backlog.mjs';
+
+const PHASES = new Set([
+  'engineering_bootstrap',
+  'discovery',
+  'engineering',
+  'planning',
+  'backlog_planning',
+  'work_item_plan_approval',
+  'build',
+  'implementation',
+  'review',
+  'work_item_review',
+  'reconcile',
+  'migration_reconciliation',
+  'complete'
+]);
+const STOP_REASONS = new Set([null, 'consequential_decision', 'external_action', 'unrecoverable_blocker', 'finished']);
+
+export function emptyState() {
+  return {
+    schema_version: 1,
+    execution: { id: null, phase: 'discovery', step: 'define_project', workflow_hash: null },
+    active: { work_item: null, task: null },
+    stop_reason: null,
+    migration: { status: 'not_required' }
+  };
+}
+
+export function parseState(text, { source = 'state.yaml' } = {}) {
+  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length) throw new ArtifactValidationError(`${source} is invalid: ${document.errors[0].message}`);
+  const value = document.toJS();
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new ArtifactValidationError(`${source} must be a mapping.`);
+  if (value.schema_version !== 1) throw new ArtifactValidationError(`${source} schema_version must be 1.`);
+  const phase = value.execution?.phase;
+  if (!PHASES.has(phase)) throw new ArtifactValidationError(`${source} execution.phase is invalid.`);
+  if (!STOP_REASONS.has(value.stop_reason ?? null))
+    throw new ArtifactValidationError(`${source} stop_reason is invalid.`);
+  if (!['not_required', 'pending_reconciliation', 'completed'].includes(value.migration?.status ?? 'not_required'))
+    throw new ArtifactValidationError(`${source} migration.status is invalid.`);
+  return {
+    schema_version: 1,
+    execution: {
+      id: value.execution?.id ?? null,
+      phase,
+      step: value.execution?.step ?? null,
+      workflow_hash: value.execution?.workflow_hash ?? null
+    },
+    active: {
+      work_item: value.active?.work_item ?? null,
+      task: value.active?.task ?? null
+    },
+    stop_reason: value.stop_reason ?? null,
+    migration: value.migration ?? { status: 'not_required' }
+  };
+}
+
+export function stringifyState(state) {
+  return stringify(state, { lineWidth: 0 });
+}

package/src/artifacts/tasks.mjs

@@ -0,0 +1,90 @@
+import { parseDocument } from 'yaml';
+import { ArtifactValidationError } from './backlog.mjs';
+
+const STATES = new Set(['pending', 'in_progress', 'completed']);
+const TASK_ID = /^T\d{3,}$/;
+
+function fail(message) {
+  throw new ArtifactValidationError(message);
+}
+function requireObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${label} must be a mapping.`);
+  return value;
+}
+function requireString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) fail(`${label} must be a non-empty string.`);
+  return value.trim();
+}
+
+export function parseTasks(text, { source = 'tasks.yaml', expectedWorkItem = null } = {}) {
+  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+  if (document.errors.length) fail(`${source} is invalid: ${document.errors[0].message}`);
+  const value = requireObject(document.toJS(), source);
+  if (value.schema_version !== 1) fail(`${source} schema_version must be 1.`);
+  const workItem = requireString(value.work_item, `${source} work_item`);
+  if (expectedWorkItem && workItem !== expectedWorkItem)
+    fail(`${source} belongs to ${workItem}, expected ${expectedWorkItem}.`);
+  if (!Array.isArray(value.tasks)) fail(`${source} tasks must be a list.`);
+  const ids = new Set();
+  const tasks = value.tasks.map((raw, index) => {
+    const label = `tasks[${index}]`;
+    const task = requireObject(raw, label);
+    const id = requireString(task.id, `${label}.id`);
+    if (!TASK_ID.test(id)) fail(`${label}.id must use T followed by a zero-padded numeric sequence, e.g. T003.`);
+    if (ids.has(id)) fail(`${source} contains duplicate task ID '${id}'.`);
+    ids.add(id);
+    const title = requireString(task.title, `${label}.title`);
+    const state = task.state ?? task.status;
+    if (!STATES.has(state)) fail(`${label}.state must be pending, in_progress, or completed.`);
+    if (!Array.isArray(task.depends_on ?? [])) fail(`${label}.depends_on must be a list.`);
+    const dependencies = [...new Set(task.depends_on ?? [])];
+    if (dependencies.length !== (task.depends_on ?? []).length) fail(`${id} contains duplicate task dependencies.`);
+    for (const dependency of dependencies) {
+      if (!TASK_ID.test(dependency)) fail(`${id} depends on invalid task ID '${dependency}'.`);
+      if (dependency === id) fail(`${id} cannot depend on itself.`);
+    }
+    const implementation = task.implementation ?? 'commit';
+    if (!['commit', 'none', 'legacy'].includes(implementation))
+      fail(`${id}.implementation must be commit, none or legacy.`);
+    if (implementation === 'legacy' && state !== 'completed')
+      fail(`${id}: legacy is reserved for completed migrated tasks.`);
+    return {
+      id,
+      title,
+      state,
+      depends_on: dependencies,
+      implementation,
+      ...(task.legacy_commit ? { legacy_commit: task.legacy_commit } : {})
+    };
+  });
+  const byId = new Map(tasks.map((task) => [task.id, task]));
+  for (const task of tasks)
+    for (const dependency of task.depends_on)
+      if (!byId.has(dependency)) fail(`${task.id} depends on unknown task '${dependency}'.`);
+  validateTaskDag(tasks);
+  if (tasks.filter((task) => task.state === 'in_progress').length > 1)
+    fail('Only one mutating task may be in_progress.');
+  return { schema_version: 1, work_item: workItem, tasks };
+}
+
+function validateTaskDag(tasks) {
+  const indegree = new Map(tasks.map((task) => [task.id, task.depends_on.length]));
+  const dependents = new Map(tasks.map((task) => [task.id, []]));
+  for (const task of tasks) for (const dependency of task.depends_on) dependents.get(dependency).push(task.id);
+  const queue = tasks.filter((task) => task.depends_on.length === 0).map((task) => task.id);
+  let visited = 0;
+  while (queue.length) {
+    const id = queue.shift();
+    visited += 1;
+    for (const dependent of dependents.get(id)) {
+      const next = indegree.get(dependent) - 1;
+      indegree.set(dependent, next);
+      if (next === 0) queue.push(dependent);
+    }
+  }
+  if (visited !== tasks.length) fail('tasks.yaml task dependencies contain a cycle.');
+}
+
+export function qualifiedTaskId(workItem, task) {
+  return `${workItem}-${task}`;
+}