@shahmarasy/prodo 0.1.4 → 0.1.6

package/src/core/terminology.ts

@@ -0,0 +1,177 @@
+import { parseMarkdownSections } from "./markdown";
+import type { NormalizedBrief } from "./normalized-brief";
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+
+type LoadedArtifact = {
+  type: ArtifactType;
+  file: string;
+  doc: ArtifactDoc;
+};
+
+export type TermEntry = {
+  term: string;
+  normalizedTerm: string;
+  definition?: string;
+  sources: Array<{ artifactType: ArtifactType | "brief"; file: string; heading?: string }>;
+};
+
+export type TermMap = Map<string, TermEntry>;
+
+function normalizeTerm(term: string): string {
+  return term
+    .toLowerCase()
+    .replace(/[^a-z0-9\u00c0-\u024f\s]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function extractBoldTerms(body: string): string[] {
+  const matches = body.match(/\*\*([^*]+)\*\*/g) ?? [];
+  return matches
+    .map((m) => m.replace(/\*\*/g, "").trim())
+    .filter((t) => t.length > 2 && t.length < 60);
+}
+
+export function buildTermMap(
+  normalizedBrief: NormalizedBrief,
+  loadedArtifacts: LoadedArtifact[]
+): TermMap {
+  const termMap: TermMap = new Map();
+
+  function addTerm(term: string, source: TermEntry["sources"][0], definition?: string): void {
+    const normalized = normalizeTerm(term);
+    if (!normalized || normalized.length < 2) return;
+
+    const existing = termMap.get(normalized);
+    if (existing) {
+      existing.sources.push(source);
+      if (definition && !existing.definition) {
+        existing.definition = definition;
+      }
+    } else {
+      termMap.set(normalized, {
+        term,
+        normalizedTerm: normalized,
+        definition,
+        sources: [source]
+      });
+    }
+  }
+
+  addTerm(normalizedBrief.product_name, { artifactType: "brief", file: "brief.md" });
+
+  for (const goal of normalizedBrief.goals) {
+    addTerm(goal, { artifactType: "brief", file: "brief.md" }, goal);
+  }
+  for (const feature of normalizedBrief.core_features) {
+    addTerm(feature, { artifactType: "brief", file: "brief.md" }, feature);
+  }
+  for (const constraint of normalizedBrief.constraints) {
+    addTerm(constraint, { artifactType: "brief", file: "brief.md" }, constraint);
+  }
+
+  for (const contract of normalizedBrief.contracts.goals) {
+    addTerm(contract.text, { artifactType: "brief", file: "brief.md" }, contract.text);
+  }
+  for (const contract of normalizedBrief.contracts.core_features) {
+    addTerm(contract.text, { artifactType: "brief", file: "brief.md" }, contract.text);
+  }
+  for (const contract of normalizedBrief.contracts.constraints) {
+    addTerm(contract.text, { artifactType: "brief", file: "brief.md" }, contract.text);
+  }
+
+  for (const artifact of loadedArtifacts) {
+    const sections = parseMarkdownSections(artifact.doc.body);
+    for (const section of sections) {
+      if (section.level === 2) {
+        addTerm(section.heading, {
+          artifactType: artifact.type,
+          file: artifact.file,
+          heading: section.heading
+        });
+      }
+    }
+
+    const boldTerms = extractBoldTerms(artifact.doc.body);
+    for (const boldTerm of boldTerms) {
+      addTerm(boldTerm, { artifactType: artifact.type, file: artifact.file });
+    }
+  }
+
+  return termMap;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0) as number[]);
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+function sharesStem(a: string, b: string): boolean {
+  const wordsA = a.split(/\s+/).filter((w) => w.length > 3);
+  const wordsB = b.split(/\s+/).filter((w) => w.length > 3);
+  for (const wa of wordsA) {
+    for (const wb of wordsB) {
+      const shorter = Math.min(wa.length, wb.length);
+      const prefix = Math.min(4, shorter);
+      if (wa.slice(0, prefix) === wb.slice(0, prefix) && wa !== wb) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function checkTermReconciliation(termMap: TermMap): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const entries = Array.from(termMap.values()).filter(
+    (e) => e.sources.length > 0 && e.normalizedTerm.length > 3
+  );
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+
+      if (a.normalizedTerm === b.normalizedTerm) continue;
+
+      const dist = levenshtein(a.normalizedTerm, b.normalizedTerm);
+      const maxLen = Math.max(a.normalizedTerm.length, b.normalizedTerm.length);
+      const ratio = dist / maxLen;
+
+      const isSimilar = (ratio < 0.25 && maxLen > 5) || sharesStem(a.normalizedTerm, b.normalizedTerm);
+
+      if (isSimilar) {
+        const aTypes = [...new Set(a.sources.map((s) => s.artifactType))];
+        const bTypes = [...new Set(b.sources.map((s) => s.artifactType))];
+        const crossDoc = aTypes.some((t) => !bTypes.includes(t)) || bTypes.some((t) => !aTypes.includes(t));
+
+        if (crossDoc) {
+          issues.push({
+            level: "warning",
+            code: "term_inconsistency",
+            check: "terminology",
+            message: `Similar terms used across documents: "${a.term}" (${aTypes.join(", ")}) vs "${b.term}" (${bTypes.join(", ")})`,
+            suggestion: "Standardize terminology across all artifacts to avoid ambiguity."
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}

package/src/core/tracing.ts

@@ -0,0 +1,110 @@
+import { taggedLinesByContract } from "./markdown";
+import { parseNormalizedBriefOrThrow, type NormalizedBrief, type BriefContractItem } from "./normalized-brief";
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+
+type LoadedArtifact = {
+  type: ArtifactType;
+  file: string;
+  doc: ArtifactDoc;
+};
+
+export type TraceEntry = {
+  contractId: string;
+  contractText: string;
+  category: "goals" | "core_features" | "constraints";
+  references: Array<{
+    artifactType: ArtifactType;
+    file: string;
+    line: string;
+  }>;
+};
+
+export type TraceMap = Map<string, TraceEntry>;
+
+export function buildTraceMap(
+  normalizedBrief: NormalizedBrief,
+  loadedArtifacts: LoadedArtifact[]
+): TraceMap {
+  const traceMap: TraceMap = new Map();
+
+  function registerContracts(
+    items: BriefContractItem[],
+    category: TraceEntry["category"]
+  ): void {
+    for (const item of items) {
+      traceMap.set(item.id, {
+        contractId: item.id,
+        contractText: item.text,
+        category,
+        references: []
+      });
+    }
+  }
+
+  registerContracts(normalizedBrief.contracts.goals, "goals");
+  registerContracts(normalizedBrief.contracts.core_features, "core_features");
+  registerContracts(normalizedBrief.contracts.constraints, "constraints");
+
+  for (const artifact of loadedArtifacts) {
+    const tagged = taggedLinesByContract(artifact.doc.body);
+    for (const { contractId, line } of tagged) {
+      const entry = traceMap.get(contractId);
+      if (entry) {
+        entry.references.push({
+          artifactType: artifact.type,
+          file: artifact.file,
+          line
+        });
+      }
+    }
+  }
+
+  return traceMap;
+}
+
+export function checkRequirementCompleteness(
+  traceMap: TraceMap,
+  normalizedBrief: NormalizedBrief,
+  presentArtifactTypes: ArtifactType[]
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (presentArtifactTypes.length === 0) return issues;
+
+  for (const [contractId, entry] of traceMap) {
+    if (entry.references.length === 0) {
+      issues.push({
+        level: "warning",
+        code: "untraced_requirement",
+        check: "tracing",
+        message: `Contract ${contractId} ("${truncate(entry.contractText, 60)}") is not referenced in any generated artifact.`,
+        suggestion: `Ensure [${contractId}] tag appears in at least one artifact body.`
+      });
+    }
+  }
+
+  const hasPrd = presentArtifactTypes.includes("prd");
+  if (hasPrd) {
+    for (const [contractId, entry] of traceMap) {
+      if (entry.category === "goals") {
+        const inPrd = entry.references.some((r) => r.artifactType === "prd");
+        if (!inPrd && entry.references.length > 0) {
+          issues.push({
+            level: "warning",
+            code: "goal_missing_in_prd",
+            check: "tracing",
+            message: `Goal ${contractId} appears in downstream artifacts but is not traced in the PRD.`,
+            suggestion: `Add [${contractId}] tag to the PRD to maintain traceability.`
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3)}...`;
+}

package/src/{types.ts → core/types.ts}

@@ -1,46 +1,46 @@
-export const CORE_ARTIFACT_TYPES = ["prd", "workflow", "wireframe", "stories", "techspec"] as const;
-export const ARTIFACT_TYPES = CORE_ARTIFACT_TYPES;
-
-export type CoreArtifactType = (typeof CORE_ARTIFACT_TYPES)[number];
-export type ArtifactType = CoreArtifactType | string;
-
-export type ArtifactDoc = {
-  frontmatter: Record<string, unknown>;
-  body: string;
-};
-
-export type ContractCoverage = {
-  goals: string[];
-  core_features: string[];
-  constraints: string[];
-};
-
-export type ValidationIssue = {
-  level: "error" | "warning";
-  code: string;
-  check?: "schema" | "tag_coverage" | "semantic_consistency" | "contract_relevance";
-  artifactType?: ArtifactType;
-  file?: string;
-  field?: string;
-  message: string;
-  suggestion?: string;
-};
-
-export type GenerateResult = {
-  body: string;
-  frontmatter?: Record<string, unknown>;
-};
-
-export type ProviderSchemaHint = {
-  artifactType: ArtifactType | "normalize" | "semantic_consistency" | "contract_relevance";
-  requiredHeadings: string[];
-  requiredContracts: Array<keyof ContractCoverage>;
-};
-
-export type LLMProvider = {
-  generate: (
-    prompt: string,
-    inputContext: Record<string, unknown>,
-    schemaHint: ProviderSchemaHint
-  ) => Promise<GenerateResult>;
-};
+export const CORE_ARTIFACT_TYPES = ["prd", "workflow", "wireframe", "stories", "techspec"] as const;
+export const ARTIFACT_TYPES = CORE_ARTIFACT_TYPES;
+
+export type CoreArtifactType = (typeof CORE_ARTIFACT_TYPES)[number];
+export type ArtifactType = CoreArtifactType | string;
+
+export type ArtifactDoc = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+export type ContractCoverage = {
+  goals: string[];
+  core_features: string[];
+  constraints: string[];
+};
+
+export type ValidationIssue = {
+  level: "error" | "warning";
+  code: string;
+  check?: "schema" | "tag_coverage" | "semantic_consistency" | "contract_relevance" | "terminology" | "tracing" | "cross_reference";
+  artifactType?: ArtifactType;
+  file?: string;
+  field?: string;
+  message: string;
+  suggestion?: string;
+};
+
+export type GenerateResult = {
+  body: string;
+  frontmatter?: Record<string, unknown>;
+};
+
+export type ProviderSchemaHint = {
+  artifactType: ArtifactType | "normalize" | "semantic_consistency" | "contract_relevance";
+  requiredHeadings: string[];
+  requiredContracts: Array<keyof ContractCoverage>;
+};
+
+export type LLMProvider = {
+  generate: (
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ) => Promise<GenerateResult>;
+};

package/src/{utils.ts → core/utils.ts}

@@ -1,64 +1,64 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-export async function ensureDir(dirPath: string): Promise<void> {
-  await fs.mkdir(dirPath, { recursive: true });
-}
-
-export async function fileExists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function readJsonFile<T>(filePath: string): Promise<T> {
-  const raw = await fs.readFile(filePath, "utf8");
-  return JSON.parse(raw) as T;
-}
-
-export function timestampSlug(date = new Date()): string {
-  return date.toISOString().replace(/[:.]/g, "-");
-}
-
-function pad2(value: number): string {
-  return String(value).padStart(2, "0");
-}
-
-export function artifactFileStamp(date = new Date()): string {
-  const year = date.getFullYear();
-  const month = pad2(date.getMonth() + 1);
-  const day = pad2(date.getDate());
-  const hour = pad2(date.getHours());
-  const minute = pad2(date.getMinutes());
-  const second = pad2(date.getSeconds());
-  return `${year}${month}${day}-${hour}${minute}${second}`;
-}
-
-export async function listFilesSortedByMtime(dirPath: string): Promise<string[]> {
-  const exists = await fileExists(dirPath);
-  if (!exists) return [];
-
-  const entries = await fs.readdir(dirPath);
-  const withStats = await Promise.all(
-    entries.map(async (name) => {
-      const fullPath = path.join(dirPath, name);
-      const stat = await fs.stat(fullPath);
-      return { fullPath, mtimeMs: stat.mtimeMs, isFile: stat.isFile() };
-    })
-  );
-
-  return withStats
-    .filter((entry) => entry.isFile)
-    .sort((a, b) => b.mtimeMs - a.mtimeMs)
-    .map((entry) => entry.fullPath);
-}
-
-export function isPathInside(parentDir: string, candidatePath: string): boolean {
-  const parent = path.resolve(parentDir);
-  const child = path.resolve(candidatePath);
-  const relative = path.relative(parent, child);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJsonFile<T>(filePath: string): Promise<T> {
+  const raw = await fs.readFile(filePath, "utf8");
+  return JSON.parse(raw) as T;
+}
+
+export function timestampSlug(date = new Date()): string {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+
+function pad2(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+export function artifactFileStamp(date = new Date()): string {
+  const year = date.getFullYear();
+  const month = pad2(date.getMonth() + 1);
+  const day = pad2(date.getDate());
+  const hour = pad2(date.getHours());
+  const minute = pad2(date.getMinutes());
+  const second = pad2(date.getSeconds());
+  return `${year}${month}${day}-${hour}${minute}${second}`;
+}
+
+export async function listFilesSortedByMtime(dirPath: string): Promise<string[]> {
+  const exists = await fileExists(dirPath);
+  if (!exists) return [];
+
+  const entries = await fs.readdir(dirPath);
+  const withStats = await Promise.all(
+    entries.map(async (name) => {
+      const fullPath = path.join(dirPath, name);
+      const stat = await fs.stat(fullPath);
+      return { fullPath, mtimeMs: stat.mtimeMs, isFile: stat.isFile() };
+    })
+  );
+
+  return withStats
+    .filter((entry) => entry.isFile)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .map((entry) => entry.fullPath);
+}
+
+export function isPathInside(parentDir: string, candidatePath: string): boolean {
+  const parent = path.resolve(parentDir);
+  const child = path.resolve(candidatePath);
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}