@shahmarasy/prodo 0.1.0

package/src/validate.ts

@@ -0,0 +1,246 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import { listArtifactDefinitions } from "./artifact-registry";
+import { checkConsistency } from "./consistency";
+import { UserError } from "./errors";
+import { getActiveArtifactPath } from "./output-index";
+import { normalizedBriefPath, outputDirPath, reportPath } from "./paths";
+import { extractRequiredHeadingsFromTemplate, resolveTemplate } from "./template-resolver";
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+import { ensureDir, fileExists, isPathInside, listFilesSortedByMtime, readJsonFile } from "./utils";
+import { validateSchema } from "./validator";
+
+type LoadedArtifact = {
+  type: ArtifactType;
+  file: string;
+  doc: ArtifactDoc;
+};
+
+function sidecarPath(filePath: string): string {
+  const parsed = path.parse(filePath);
+  return path.join(parsed.dir, `${parsed.name}.artifact.json`);
+}
+
+async function loadArtifactDoc(filePath: string): Promise<ArtifactDoc> {
+  const sidecar = sidecarPath(filePath);
+  if (await fileExists(sidecar)) {
+    const payload = await readJsonFile<Record<string, unknown>>(sidecar);
+    return {
+      frontmatter: (payload.frontmatter as Record<string, unknown>) ?? {},
+      body: typeof payload.body === "string" ? payload.body : ""
+    };
+  }
+  const raw = await fs.readFile(filePath, "utf8");
+  const parsed = matter(raw);
+  return {
+    frontmatter: parsed.data as Record<string, unknown>,
+    body: parsed.content
+  };
+}
+
+async function loadLatestArtifacts(cwd: string): Promise<LoadedArtifact[]> {
+  const defs = await listArtifactDefinitions(cwd);
+  const loaded: LoadedArtifact[] = [];
+  for (const def of defs) {
+    const type = def.name;
+    const active = await getActiveArtifactPath(cwd, type);
+    const fallback = async (): Promise<string | undefined> => {
+      const files = await listFilesSortedByMtime(outputDirPath(cwd, type, def.output_dir));
+      return files[0];
+    };
+    const latest = active ?? (await fallback());
+    if (!latest) continue;
+    const parsed = await loadArtifactDoc(latest);
+    loaded.push({
+      type,
+      file: latest,
+      doc: parsed
+    });
+  }
+  return loaded;
+}
+
+async function listHtmlFiles(dir: string): Promise<string[]> {
+  if (!(await fileExists(dir))) return [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+    .map((entry) => path.join(dir, entry.name));
+}
+
+function formatIssue(issue: ValidationIssue): string {
+  const location = issue.file ? ` (${issue.file})` : "";
+  const field = issue.field ? ` [${issue.field}]` : "";
+  const check = issue.check ? ` [${issue.check}]` : "";
+  const fix = issue.suggestion ? `\n  Suggestion: ${issue.suggestion}` : "";
+  return `- [${issue.level.toUpperCase()}] ${issue.code}${check}${field}: ${issue.message}${location}${fix}`;
+}
+
+async function writeReport(targetPath: string, issues: ValidationIssue[]): Promise<void> {
+  const status = issues.some((issue) => issue.level === "error") ? "FAIL" : "PASS";
+  const schemaIssues = issues.filter((issue) => issue.check === "schema");
+  const coverageIssues = issues.filter((issue) => issue.check === "tag_coverage");
+  const relevanceIssues = issues.filter((issue) => issue.check === "contract_relevance");
+  const semanticIssues = issues.filter((issue) => issue.check === "semantic_consistency");
+  const gate = (set: ValidationIssue[]) => (set.some((issue) => issue.level === "error") ? "FAIL" : "PASS");
+  const content = [
+    "# Prodo Validation Report",
+    "",
+    `Status: **${status}**`,
+    `Generated at: ${new Date().toISOString()}`,
+    "",
+    "## Gate Results",
+    `- Schema pass: ${gate(schemaIssues)}`,
+    `- Tag coverage pass: ${gate(coverageIssues)}`,
+    `- Contract relevance pass: ${gate(relevanceIssues)}`,
+    `- Semantic consistency pass: ${gate(semanticIssues)}`,
+    "",
+    "## Findings",
+    issues.length === 0 ? "- No issues found." : issues.map(formatIssue).join("\n"),
+    ""
+  ].join("\n");
+
+  await ensureDir(path.dirname(targetPath));
+  await fs.writeFile(targetPath, content, "utf8");
+}
+
+export async function runValidate(
+  cwd: string,
+  options: { strict?: boolean; report?: string }
+): Promise<{ pass: boolean; reportPath: string; issues: ValidationIssue[] }> {
+  const normalizedPath = normalizedBriefPath(cwd);
+  if (!(await fileExists(normalizedPath))) {
+    throw new UserError("Missing `.prodo/briefs/normalized-brief.json`. Run `prodo-init` and create it first.");
+  }
+
+  const normalizedBrief = await readJsonFile<Record<string, unknown>>(normalizedPath);
+  const loaded = await loadLatestArtifacts(cwd);
+  const issues: ValidationIssue[] = [];
+
+  for (const artifact of loaded) {
+    const template = await resolveTemplate({
+      cwd,
+      artifactType: artifact.type
+    });
+    const headings = template ? extractRequiredHeadingsFromTemplate(template.content) : [];
+    const schemaCheck = await validateSchema(
+      cwd,
+      artifact.type,
+      artifact.doc,
+      headings
+    );
+    issues.push(...schemaCheck.issues.map((issue) => ({ ...issue, file: artifact.file })));
+
+    if (artifact.type === "workflow") {
+      const ext = path.extname(artifact.file).toLowerCase();
+      if (ext !== ".md") {
+        issues.push({
+          level: "error",
+          code: "workflow_markdown_missing",
+          check: "schema",
+          artifactType: artifact.type,
+          file: artifact.file,
+          message: "Workflow explanation artifact must be Markdown (.md).",
+          suggestion: "Regenerate workflow so explanation is written to .md."
+        });
+      }
+      const mmdPath = path.join(path.dirname(artifact.file), `${path.parse(artifact.file).name}.mmd`);
+      if (!(await fileExists(mmdPath))) {
+        issues.push({
+          level: "error",
+          code: "workflow_mermaid_missing",
+          check: "schema",
+          artifactType: artifact.type,
+          file: artifact.file,
+          message: "Workflow Mermaid companion file (.mmd) is missing.",
+          suggestion: "Regenerate workflow so markdown and .mmd are produced as a pair."
+        });
+      } else {
+        const mmdRaw = await fs.readFile(mmdPath, "utf8");
+        const mermaidLike = /(^|\n)\s*flowchart\s+/i.test(mmdRaw) || /(^|\n)\s*graph\s+/i.test(mmdRaw);
+        if (!mermaidLike) {
+          issues.push({
+            level: "error",
+            code: "workflow_mermaid_invalid",
+            check: "schema",
+            artifactType: artifact.type,
+            file: mmdPath,
+            message: "Workflow Mermaid file is invalid or prose-only.",
+            suggestion: "Ensure .mmd file contains valid Mermaid diagram syntax."
+          });
+        }
+      }
+    }
+
+    if (artifact.type === "wireframe") {
+      const ext = path.extname(artifact.file).toLowerCase();
+      if (ext !== ".md") {
+        issues.push({
+          level: "error",
+          code: "wireframe_markdown_missing",
+          check: "schema",
+          artifactType: artifact.type,
+          file: artifact.file,
+          message: "Wireframe explanation artifact must be Markdown (.md).",
+          suggestion: "Regenerate wireframe so explanation is written to .md."
+        });
+      }
+
+      const htmlPath = path.join(path.dirname(artifact.file), `${path.parse(artifact.file).name}.html`);
+      if (!(await fileExists(htmlPath))) {
+        issues.push({
+          level: "error",
+          code: "wireframe_html_missing",
+          check: "schema",
+          artifactType: artifact.type,
+          file: artifact.file,
+          message: "Wireframe HTML companion file is missing.",
+          suggestion: "Regenerate wireframe so markdown and .html are produced as a pair."
+        });
+      } else {
+        const htmlRaw = await fs.readFile(htmlPath, "utf8");
+        const htmlLooksValid = /<!doctype html>/i.test(htmlRaw) || /<html[\s>]/i.test(htmlRaw);
+        if (!htmlLooksValid) {
+          issues.push({
+            level: "error",
+            code: "wireframe_html_invalid",
+            check: "schema",
+            artifactType: artifact.type,
+            file: htmlPath,
+            message: "Wireframe output is not valid HTML content.",
+            suggestion: "Ensure wireframe companion HTML contains a valid document structure."
+          });
+        }
+      }
+
+      const htmlFiles = await listHtmlFiles(path.dirname(artifact.file));
+      if (htmlFiles.length < 1) {
+        issues.push({
+          level: "error",
+          code: "wireframe_screens_missing",
+          check: "schema",
+          artifactType: artifact.type,
+          file: artifact.file,
+          message: "Wireframe must include at least one HTML screen artifact.",
+          suggestion: "Regenerate wireframe to create paired .md and .html screen files."
+        });
+      }
+    }
+  }
+
+  issues.push(...(await checkConsistency(cwd, loaded, normalizedBrief)));
+  if (options.strict) {
+    for (const issue of issues) {
+      if (issue.level === "warning") issue.level = "error";
+    }
+  }
+
+  const finalReportPath = options.report ? path.resolve(cwd, options.report) : reportPath(cwd);
+  if (!isPathInside(path.join(cwd, "product-docs"), finalReportPath)) {
+    throw new UserError("Validation report must be inside `product-docs/`.");
+  }
+  await writeReport(finalReportPath, issues);
+  const pass = !issues.some((issue) => issue.level === "error");
+  return { pass, reportPath: finalReportPath, issues };
+}

package/src/validator.ts

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import Ajv2020 from "ajv/dist/2020";
+import addFormats from "ajv-formats";
+import yaml from "js-yaml";
+import { sectionTextMap } from "./markdown";
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+import { schemaPath } from "./paths";
+
+type SchemaWithHeading = Record<string, unknown> & {
+  x_required_headings?: unknown;
+};
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv);
+
+async function resolveSchema(
+  cwd: string,
+  artifactType: ArtifactType
+): Promise<SchemaWithHeading> {
+  const raw = await fs.readFile(schemaPath(cwd, artifactType), "utf8");
+  return yaml.load(raw) as SchemaWithHeading;
+}
+
+function requiredHeadingsFromSchema(schema: SchemaWithHeading): string[] {
+  if (!Array.isArray(schema.x_required_headings)) return [];
+  return schema.x_required_headings.filter((item): item is string => typeof item === "string");
+}
+
+export async function validateSchema(
+  cwd: string,
+  artifactType: ArtifactType,
+  doc: ArtifactDoc,
+  requiredHeadingsOverride?: string[]
+): Promise<{ issues: ValidationIssue[]; requiredHeadings: string[] }> {
+  const schema = await resolveSchema(cwd, artifactType);
+  const requiredHeadings =
+    requiredHeadingsOverride && requiredHeadingsOverride.length > 0
+      ? requiredHeadingsOverride
+      : requiredHeadingsFromSchema(schema);
+  const workingSchema: Record<string, unknown> = { ...schema };
+  delete workingSchema.x_required_headings;
+
+  const validate = ajv.compile(workingSchema);
+  const valid = validate(doc);
+  const issues: ValidationIssue[] = [];
+
+  if (!valid && validate.errors) {
+    for (const err of validate.errors) {
+      issues.push({
+        level: "error",
+        code: "schema_validation_failed",
+        check: "schema",
+        artifactType,
+        field: err.instancePath || err.schemaPath,
+        message: `Schema validation error: ${err.message ?? "unknown error"}`,
+        suggestion: "Adjust the generated content to satisfy schema requirements."
+      });
+    }
+  }
+
+  const sections = sectionTextMap(doc.body);
+  const trMode = String((doc.frontmatter as Record<string, unknown>).language ?? "").toLowerCase().startsWith("tr");
+  if (trMode) {
+    return { issues, requiredHeadings: [] };
+  }
+  for (const heading of requiredHeadings) {
+    if (!doc.body.includes(heading)) {
+      issues.push({
+        level: "error",
+        code: "missing_required_heading",
+        check: "schema",
+        artifactType,
+        field: heading,
+        message: `Required section missing: ${heading}`,
+        suggestion: "Regenerate or manually edit the artifact to include all required headings."
+      });
+      continue;
+    }
+
+    const content = sections.get(heading) ?? "";
+    const isPlaceholder = /(tbd|to be defined|i don't know|unknown|n\/a)/i.test(content);
+    if (content.trim().length < 20 || isPlaceholder) {
+      issues.push({
+        level: "error",
+        code: "weak_required_heading_content",
+        check: "schema",
+        artifactType,
+        field: heading,
+        message: `Section has weak or placeholder content: ${heading}`,
+        suggestion: "Replace placeholders with concrete, actionable details."
+      });
+    }
+  }
+
+  return { issues, requiredHeadings };
+}

package/src/version.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileExists } from "./utils";
+
+export async function readCliVersion(cwd: string): Promise<string> {
+  const candidates = [
+    path.join(cwd, "package.json"),
+    path.resolve(__dirname, "..", "package.json")
+  ];
+  for (const candidate of candidates) {
+    if (!(await fileExists(candidate))) continue;
+    try {
+      const raw = await fs.readFile(candidate, "utf8");
+      const parsed = JSON.parse(raw) as { version?: unknown };
+      if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+        return parsed.version.trim();
+      }
+    } catch {
+      // ignore and continue
+    }
+  }
+  return "0.0.0";
+}
+

package/src/workflow-commands.ts

@@ -0,0 +1,31 @@
+export type WorkflowCommand = {
+  name: string;
+  cliSubcommand: string;
+  description: string;
+};
+
+const BASE_WORKFLOW_COMMANDS: WorkflowCommand[] = [
+  { name: "prodo-normalize", cliSubcommand: "normalize", description: "Normalize start brief into normalized brief JSON." },
+  { name: "prodo-prd", cliSubcommand: "prd", description: "Generate PRD artifact from normalized brief." },
+  { name: "prodo-workflow", cliSubcommand: "workflow", description: "Generate workflow artifact." },
+  { name: "prodo-wireframe", cliSubcommand: "wireframe", description: "Generate wireframe artifact." },
+  { name: "prodo-stories", cliSubcommand: "stories", description: "Generate stories artifact." },
+  { name: "prodo-techspec", cliSubcommand: "techspec", description: "Generate technical specification artifact." },
+  { name: "prodo-validate", cliSubcommand: "validate", description: "Run schema and cross-artifact consistency validation." }
+];
+
+export const WORKFLOW_COMMANDS: WorkflowCommand[] = BASE_WORKFLOW_COMMANDS;
+
+export function buildWorkflowCommands(artifactTypes: string[]): WorkflowCommand[] {
+  const commandByName = new Map<string, WorkflowCommand>(BASE_WORKFLOW_COMMANDS.map((item) => [item.name, item]));
+  for (const type of artifactTypes) {
+    const name = `prodo-${type}`;
+    if (commandByName.has(name)) continue;
+    commandByName.set(name, {
+      name,
+      cliSubcommand: type,
+      description: `Generate ${type} artifact from normalized brief.`
+    });
+  }
+  return Array.from(commandByName.values());
+}

package/templates/artifacts/prd.md

@@ -0,0 +1,219 @@
+# Product Requirements Document (PRD)
+
+---
+
+## 1. Document Control
+
+| Version | Date | Author | Description |
+|--------|------|--------|-------------|
+| v1.0 | {{date}} | {{author}} | Initial version |
+
+---
+
+## 2. Product Overview
+
+### 2.1 Product Summary
+
+{{Provide a concise description of the product, what it does, and its core value proposition.}}
+
+### 2.2 Problem Statement
+
+{{Describe the core problem being solved. Who is affected and why it matters.}}
+
+### 2.3 Goals & Objectives
+
+- **G1:** {{Primary business/product goal}}
+- **G2:** {{Secondary goal}}
+- **G3:** {{Optional}}
+
+---
+
+## 3. Functional Requirements
+
+### 3.1 Core System Logic
+
+#### Primary Features
+
+- **FR-XX-01:** {{System must...}}
+- **FR-XX-02:** {{System must...}}
+- **FR-XX-03:** {{System must...}}
+
+#### Advanced Rules / Variations
+
+- **FR-XX-04:** {{Conditional logic / variations}}
+- **FR-XX-05:** {{Behavior-based rules}}
+- **FR-XX-06:** {{Special cases}}
+
+---
+
+### 3.2 Constraints & Limits
+
+- **FR-XX-07:** {{Max limits}}
+- **FR-XX-08:** {{Time-based limits}}
+- **FR-XX-09:** {{Usage restrictions}}
+
+---
+
+### 3.3 Wallet / Balance / State Management (if applicable)
+
+- **FR-STATE-01:** {{State update logic}}
+- **FR-STATE-02:** {{User visibility}}
+- **FR-STATE-03:** {{Separation of balances/categories}}
+
+---
+
+### 3.4 Exception & Recovery Handling
+
+- **FR-ERR-01:** {{Full rollback / reversal logic}}
+- **FR-ERR-02:** {{Partial correction logic}}
+- **FR-ERR-03:** {{Negative state prevention}}
+- **FR-ERR-04:** {{User notification for corrections}}
+
+---
+
+### 3.5 Notifications
+
+- **FR-NOTIF-01:** {{Real-time notification}}
+- **FR-NOTIF-02:** {{Special case notification}}
+- **FR-NOTIF-03:** {{Periodic summary}}
+- **FR-NOTIF-04:** {{Threshold/limit warnings}}
+
+---
+
+### 3.6 Admin / Backoffice
+
+- **FR-ADMIN-01:** {{Rule management}}
+- **FR-ADMIN-02:** {{Configuration control}}
+- **FR-ADMIN-03:** {{Fraud/manual intervention}}
+- **FR-ADMIN-04:** {{Audit & monitoring}}
+
+---
+
+## 4. Non-Functional Requirements
+
+### 4.1 Performance
+
+- **NFR-PERF-01:** {{Latency requirements}}
+- **NFR-PERF-02:** {{Throughput requirements}}
+- **NFR-PERF-03:** {{API performance}}
+
+---
+
+### 4.2 Security
+
+- **NFR-SEC-01:** {{Fraud detection / abuse prevention}}
+- **NFR-SEC-02:** {{Auditability}}
+- **NFR-SEC-03:** {{Encryption / data protection}}
+
+---
+
+### 4.3 Reliability
+
+- **NFR-REL-01:** {{Uptime}}
+- **NFR-REL-02:** {{Failure handling}}
+- **NFR-REL-03:** {{Graceful degradation}}
+
+---
+
+### 4.4 Scalability
+
+- **NFR-SCAL-01:** {{Horizontal scalability}}
+- **NFR-SCAL-02:** {{Traffic spikes}}
+
+---
+
+## 5. Data Requirements
+
+### 5.1 Data Entities
+
+- {{Entity 1}}
+- {{Entity 2}}
+- {{Entity 3}}
+
+---
+
+### 5.2 Data Retention
+
+- {{Retention rule 1}}
+- {{Retention rule 2}}
+
+---
+
+## 6. Integrations & Constraints
+
+### 6.1 External Integrations
+
+- {{Integration 1}}
+- {{Integration 2}}
+- {{Integration 3}}
+
+---
+
+### 6.2 Technical Constraints
+
+- {{Platform constraints}}
+- {{Database constraints}}
+- {{Compliance constraints}}
+
+---
+
+### 6.3 Performance Targets
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| {{metric}} | {{target}} | {{method}} |
+
+---
+
+## 7. User Flows
+
+### Flow 1: {{Flow Name}}
+
+1. {{Step}}
+2. {{Step}}
+3. {{Step}}
+
+---
+
+### Flow 2: {{Flow Name}}
+
+1. {{Step}}
+2. {{Step}}
+
+---
+
+## 8. Compliance & Data Protection (if applicable)
+
+### 8.1 Consent Mechanism
+
+{{Describe user consent flow}}
+
+---
+
+### 8.2 Legal Notes
+
+{{Regulatory requirements and compliance context}}
+
+---
+
+## 9. Success Metrics
+
+### 9.1 Product KPIs
+
+- {{KPI 1}}
+- {{KPI 2}}
+- {{KPI 3}}
+
+---
+
+### 9.2 Operational Metrics
+
+- {{Metric 1}}
+- {{Metric 2}}
+
+---
+
+## Notes
+
+- This document defines product requirements only
+- Technical implementation must be defined in a separate TechSpec

package/templates/artifacts/stories.md

@@ -0,0 +1,49 @@
+# User Stories & Acceptance Criteria
+
+---
+
+## 1. Legend
+
+- **Priority:** P0 (Critical), P1 (High), P2 (Medium), P3 (Low)
+- **Estimate:** Story Points (Fibonacci: 1, 2, 3, 5, 8, 13)
+
+---
+
+## 2. Epic Overview
+
+- **EPIC-01:** {{Epic Name}}
+- **EPIC-02:** {{Epic Name}}
+- **EPIC-03:** {{Epic Name}}
+
+---
+
+## 3. Detailed User Stories
+
+---
+
+### EPIC-XX: {{Epic Name}}
+
+---
+
+#### US-XX: {{Short Title}}
+
+**As a** {{user type}},  
+**I want** {{desired action}},  
+**So that** {{expected outcome/value}}.
+
+- **Priority:** P0 | P1 | P2 | P3
+- **Estimate:** {{story points}} SP
+
+---
+
+### Acceptance Criteria
+
+```gherkin
+Scenario: {{Scenario name}}
+
+  Given {{initial state}}
+  When {{action happens}}
+  Then {{expected result}}
+
+  And {{additional condition}}
+  And {{additional validation}}

package/templates/artifacts/techspec.md

@@ -0,0 +1,42 @@
+# Technical Specification (TechSpec)
+
+---
+
+## 1. Document Control
+
+| Version | Date | Author | Description |
+|--------|------|--------|-------------|
+| v1.0 | {{date}} | {{author}} | Initial version |
+
+---
+
+## 2. Overview
+
+### 2.1 Purpose
+
+{{Describe what this system/component does in technical terms}}
+
+### 2.2 Scope
+
+{{Define boundaries of the system. What is included / excluded}}
+
+### 2.3 Related Documents
+
+- PRD: {{link}}
+- User Stories: {{link}}
+
+---
+
+## 3. System Architecture
+
+### 3.1 High-Level Architecture
+
+{{Describe system components and interactions}}
+
+Optional (Mermaid):
+
+```mermaid
+flowchart TD
+  A[Client] --> B[API Gateway]
+  B --> C[Service Layer]
+  C --> D[Database]