@urielsh/prodify 0.1.0

package/src/scoring/model.ts

@@ -0,0 +1,332 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { inspectCompiledContracts } from '../contracts/freshness.js';
+import { ProdifyError } from '../core/errors.js';
+import { listFilesRecursive, pathExists, writeFileEnsuringDir } from '../core/fs.js';
+import { resolveRepoPath } from '../core/paths.js';
+import type { ProdifyState, ScoreDelta, ScoreMetric, ScoreSnapshot, ScoreSnapshotKind } from '../types.js';
+
+const SCORE_SCHEMA_VERSION = '1';
+
+interface ToolOutput {
+  adapter: string;
+  details: Record<string, unknown>;
+}
+
+function roundScore(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function createMetric(options: {
+  id: string;
+  label: string;
+  tool: string;
+  weight: number;
+  ratio: number;
+  details: string;
+}): ScoreMetric {
+  const ratio = Math.max(0, Math.min(1, options.ratio));
+  const points = roundScore(options.weight * ratio);
+  return {
+    id: options.id,
+    label: options.label,
+    tool: options.tool,
+    weight: options.weight,
+    max_points: options.weight,
+    points,
+    status: ratio === 1 ? 'pass' : ratio === 0 ? 'fail' : 'partial',
+    details: options.details
+  };
+}
+
+async function detectEcosystems(repoRoot: string): Promise<string[]> {
+  const ecosystems = [];
+  if (await pathExists(resolveRepoPath(repoRoot, 'package.json'))) {
+    ecosystems.push('typescript-javascript');
+  }
+
+  const repoFiles = await listFilesRecursive(repoRoot);
+  if (repoFiles.some((file) => file.relativePath.endsWith('.py'))) {
+    ecosystems.push('python');
+  }
+
+  if (repoFiles.some((file) => file.relativePath.endsWith('.cs') || file.relativePath.endsWith('.csproj') || file.relativePath.endsWith('.sln'))) {
+    ecosystems.push('csharp');
+  }
+
+  return ecosystems.sort((left, right) => left.localeCompare(right));
+}
+
+async function buildEcosystemMetrics(repoRoot: string, ecosystems: string[]): Promise<{ metrics: ScoreMetric[]; toolOutputs: ToolOutput[] }> {
+  const metrics: ScoreMetric[] = [];
+  const toolOutputs: ToolOutput[] = [];
+
+  if (ecosystems.includes('typescript-javascript')) {
+    const packageJsonPath = resolveRepoPath(repoRoot, 'package.json');
+    const tsconfigPath = resolveRepoPath(repoRoot, 'tsconfig.json');
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')) as {
+      scripts?: Record<string, string>;
+    };
+    const scripts = packageJson.scripts ?? {};
+    const hasBuild = typeof scripts.build === 'string' && scripts.build.length > 0;
+    const hasTest = typeof scripts.test === 'string' && scripts.test.length > 0;
+    const hasTsconfig = await pathExists(tsconfigPath);
+    const score = [hasBuild, hasTest, hasTsconfig].filter(Boolean).length / 3;
+
+    metrics.push(createMetric({
+      id: 'typescript-javascript',
+      label: 'TypeScript/JavaScript local tooling',
+      tool: 'package-json',
+      weight: 15,
+      ratio: score,
+      details: `build=${hasBuild}, test=${hasTest}, tsconfig=${hasTsconfig}`
+    }));
+    toolOutputs.push({
+      adapter: 'typescript-javascript',
+      details: {
+        build_script: hasBuild,
+        test_script: hasTest,
+        tsconfig: hasTsconfig
+      }
+    });
+  }
+
+  if (ecosystems.includes('python')) {
+    const hasPyproject = await pathExists(resolveRepoPath(repoRoot, 'pyproject.toml'));
+    const hasRequirements = await pathExists(resolveRepoPath(repoRoot, 'requirements.txt'));
+    const ratio = [hasPyproject, hasRequirements].filter(Boolean).length / 2;
+
+    metrics.push(createMetric({
+      id: 'python',
+      label: 'Python local tooling',
+      tool: 'filesystem',
+      weight: 7.5,
+      ratio,
+      details: `pyproject=${hasPyproject}, requirements=${hasRequirements}`
+    }));
+    toolOutputs.push({
+      adapter: 'python',
+      details: {
+        pyproject: hasPyproject,
+        requirements: hasRequirements
+      }
+    });
+  }
+
+  if (ecosystems.includes('csharp')) {
+    const repoFiles = await listFilesRecursive(repoRoot);
+    const hasSolution = repoFiles.some((file) => file.relativePath.endsWith('.sln'));
+    const hasProject = repoFiles.some((file) => file.relativePath.endsWith('.csproj'));
+    const ratio = [hasSolution, hasProject].filter(Boolean).length / 2;
+
+    metrics.push(createMetric({
+      id: 'csharp',
+      label: 'C# local tooling',
+      tool: 'filesystem',
+      weight: 7.5,
+      ratio,
+      details: `solution=${hasSolution}, project=${hasProject}`
+    }));
+    toolOutputs.push({
+      adapter: 'csharp',
+      details: {
+        solution: hasSolution,
+        project: hasProject
+      }
+    });
+  }
+
+  return {
+    metrics,
+    toolOutputs
+  };
+}
+
+async function buildRepoHygieneMetric(repoRoot: string): Promise<{ metric: ScoreMetric; toolOutput: ToolOutput }> {
+  const requiredSignals = ['README.md', 'LICENSE', 'tests', '.prodify/contracts-src'];
+  const available = await Promise.all(requiredSignals.map((relativePath) => pathExists(resolveRepoPath(repoRoot, relativePath))));
+  const ratio = available.filter(Boolean).length / requiredSignals.length;
+
+  return {
+    metric: createMetric({
+      id: 'repo-hygiene',
+      label: 'Repository hygiene signals',
+      tool: 'filesystem',
+      weight: 20,
+      ratio,
+      details: requiredSignals.map((entry, index) => `${entry}=${available[index]}`).join(', ')
+    }),
+    toolOutput: {
+      adapter: 'filesystem',
+      details: Object.fromEntries(requiredSignals.map((entry, index) => [entry, available[index]]))
+    }
+  };
+}
+
+function buildRuntimeMetric(runtimeState: ProdifyState): { metric: ScoreMetric; toolOutput: ToolOutput } {
+  const healthyState = runtimeState.runtime.current_state !== 'failed' && runtimeState.runtime.current_state !== 'blocked';
+  const ratio = healthyState ? 1 : 0;
+
+  return {
+    metric: createMetric({
+      id: 'runtime-state',
+      label: 'Contract-driven runtime state',
+      tool: 'state-json',
+      weight: 25,
+      ratio,
+      details: `current_state=${runtimeState.runtime.current_state}, status=${runtimeState.runtime.status}`
+    }),
+    toolOutput: {
+      adapter: 'state-json',
+      details: {
+        current_state: runtimeState.runtime.current_state,
+        status: runtimeState.runtime.status,
+        last_validation_result: runtimeState.runtime.last_validation_result
+      }
+    }
+  };
+}
+
+function buildValidationMetric(runtimeState: ProdifyState): { metric: ScoreMetric; toolOutput: ToolOutput } {
+  const passed = runtimeState.runtime.last_validation?.passed === true;
+  const finalReady = runtimeState.runtime.current_state === 'validate_complete' || runtimeState.runtime.current_state === 'completed';
+  const ratio = passed ? (finalReady ? 1 : 0.5) : 0;
+
+  return {
+    metric: createMetric({
+      id: 'validation-gate',
+      label: 'Validated contract completion',
+      tool: 'state-json',
+      weight: 10,
+      ratio,
+      details: `passed=${passed}, final_ready=${finalReady}`
+    }),
+    toolOutput: {
+      adapter: 'validation-gate',
+      details: {
+        passed,
+        final_ready: finalReady
+      }
+    }
+  };
+}
+
+export async function calculateLocalScore(
+  repoRoot: string,
+  {
+    kind,
+    runtimeState
+  }: {
+    kind: ScoreSnapshotKind;
+    runtimeState: ProdifyState;
+  }
+): Promise<{ snapshot: ScoreSnapshot; toolOutputs: ToolOutput[] }> {
+  const contractInventory = await inspectCompiledContracts(repoRoot);
+  const ecosystems = await detectEcosystems(repoRoot);
+  const metrics: ScoreMetric[] = [];
+  const toolOutputs: ToolOutput[] = [];
+
+  metrics.push(createMetric({
+    id: 'contracts',
+    label: 'Compiled contract health',
+    tool: 'contract-compiler',
+    weight: 30,
+    ratio: contractInventory.ok ? 1 : Math.max(0, 1 - ((contractInventory.missingCompiledStages.length + contractInventory.staleStages.length) / 6)),
+    details: `source=${contractInventory.sourceCount}, compiled=${contractInventory.compiledCount}, stale=${contractInventory.staleStages.length}, missing=${contractInventory.missingCompiledStages.length}`
+  }));
+  toolOutputs.push({
+    adapter: 'contract-compiler',
+    details: {
+      ok: contractInventory.ok,
+      sourceCount: contractInventory.sourceCount,
+      compiledCount: contractInventory.compiledCount,
+      staleStages: contractInventory.staleStages,
+      missingCompiledStages: contractInventory.missingCompiledStages,
+      missingSourceStages: contractInventory.missingSourceStages,
+      invalidStages: contractInventory.invalidStages
+    }
+  });
+
+  const runtimeMetric = buildRuntimeMetric(runtimeState);
+  metrics.push(runtimeMetric.metric);
+  toolOutputs.push(runtimeMetric.toolOutput);
+
+  const validationMetric = buildValidationMetric(runtimeState);
+  metrics.push(validationMetric.metric);
+  toolOutputs.push(validationMetric.toolOutput);
+
+  const hygieneMetric = await buildRepoHygieneMetric(repoRoot);
+  metrics.push(hygieneMetric.metric);
+  toolOutputs.push(hygieneMetric.toolOutput);
+
+  const ecosystemMetrics = await buildEcosystemMetrics(repoRoot, ecosystems);
+  metrics.push(...ecosystemMetrics.metrics);
+  toolOutputs.push(...ecosystemMetrics.toolOutputs);
+
+  const totalScore = roundScore(metrics.reduce((sum, metric) => sum + metric.points, 0));
+  const maxScore = roundScore(metrics.reduce((sum, metric) => sum + metric.max_points, 0));
+
+  if (kind === 'final' && !(runtimeState.runtime.last_validation?.passed && (runtimeState.runtime.current_state === 'validate_complete' || runtimeState.runtime.current_state === 'completed'))) {
+    throw new ProdifyError('Final scoring requires a validated runtime state at validate_complete or completed.', {
+      code: 'SCORING_STATE_INVALID'
+    });
+  }
+
+  return {
+    snapshot: {
+      schema_version: SCORE_SCHEMA_VERSION,
+      kind,
+      ecosystems,
+      total_score: totalScore,
+      max_score: maxScore,
+      metrics
+    },
+    toolOutputs
+  };
+}
+
+function serializeJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export async function writeScoreSnapshot(
+  repoRoot: string,
+  {
+    kind,
+    runtimeState
+  }: {
+    kind: ScoreSnapshotKind;
+    runtimeState: ProdifyState;
+  }
+): Promise<ScoreSnapshot> {
+  const { snapshot, toolOutputs } = await calculateLocalScore(repoRoot, {
+    kind,
+    runtimeState
+  });
+  const metricsDir = resolveRepoPath(repoRoot, '.prodify/metrics');
+
+  await writeFileEnsuringDir(path.join(metricsDir, `${kind}.score.json`), serializeJson(snapshot));
+  await writeFileEnsuringDir(path.join(metricsDir, `${kind}.tools.json`), serializeJson({
+    schema_version: SCORE_SCHEMA_VERSION,
+    kind,
+    outputs: toolOutputs
+  }));
+
+  return snapshot;
+}
+
+export async function writeScoreDelta(repoRoot: string): Promise<ScoreDelta> {
+  const metricsDir = resolveRepoPath(repoRoot, '.prodify/metrics');
+  const baseline = JSON.parse(await fs.readFile(path.join(metricsDir, 'baseline.score.json'), 'utf8')) as ScoreSnapshot;
+  const final = JSON.parse(await fs.readFile(path.join(metricsDir, 'final.score.json'), 'utf8')) as ScoreSnapshot;
+  const delta: ScoreDelta = {
+    schema_version: SCORE_SCHEMA_VERSION,
+    baseline_score: baseline.total_score,
+    final_score: final.total_score,
+    delta: roundScore(final.total_score - baseline.total_score)
+  };
+
+  await writeFileEnsuringDir(path.join(metricsDir, 'delta.json'), serializeJson(delta));
+  return delta;
+}

package/src/skills/loader.ts

@@ -0,0 +1,58 @@
+import fs from 'node:fs/promises';
+
+import { pathExists } from '../core/fs.js';
+import { resolveCanonicalPath } from '../core/paths.js';
+import { ProdifyError } from '../core/errors.js';
+import { validateSkillDefinitionShape, validateSkillRegistryManifest } from './schema.js';
+import type { SkillDefinition, SkillRegistryManifest } from '../types.js';
+
+const SKILL_REGISTRY_PATH = '.prodify/skills/registry.json';
+
+async function readJsonFile(filePath: string, missingCode: string, invalidCode: string): Promise<unknown> {
+  if (!(await pathExists(filePath))) {
+    throw new ProdifyError(`Required skill file is missing: ${filePath}.`, {
+      code: missingCode
+    });
+  }
+
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    throw new ProdifyError(`Skill file is malformed JSON: ${filePath}.`, {
+      code: invalidCode
+    });
+  }
+}
+
+export async function readSkillRegistryManifest(repoRoot: string): Promise<SkillRegistryManifest> {
+  const registryPath = resolveCanonicalPath(repoRoot, SKILL_REGISTRY_PATH);
+  return validateSkillRegistryManifest(await readJsonFile(
+    registryPath,
+    'SKILL_REGISTRY_MISSING',
+    'SKILL_REGISTRY_INVALID'
+  ));
+}
+
+export async function loadSkillRegistry(repoRoot: string): Promise<Map<string, SkillDefinition>> {
+  const manifest = await readSkillRegistryManifest(repoRoot);
+  const registry = new Map<string, SkillDefinition>();
+
+  for (const relativePath of manifest.skills) {
+    const fullPath = resolveCanonicalPath(repoRoot, `.prodify/skills/${relativePath}`);
+    const definition = validateSkillDefinitionShape(await readJsonFile(
+      fullPath,
+      'SKILL_DEFINITION_MISSING',
+      'SKILL_DEFINITION_INVALID'
+    ));
+
+    if (registry.has(definition.id)) {
+      throw new ProdifyError(`Duplicate skill id detected: ${definition.id}.`, {
+        code: 'SKILL_REGISTRY_INVALID'
+      });
+    }
+
+    registry.set(definition.id, definition);
+  }
+
+  return registry;
+}

package/src/skills/schema.ts

@@ -0,0 +1,197 @@
+import { normalizeRepoRelativePath } from '../core/paths.js';
+import { ProdifyError } from '../core/errors.js';
+import { CONTRACT_STAGE_NAMES } from '../contracts/source-schema.js';
+import type {
+  FlowStage,
+  RepoContextFact,
+  SkillCategory,
+  SkillCondition,
+  SkillConditionPredicate,
+  SkillDefinition,
+  SkillRegistryManifest,
+  StageSkillRouting,
+  StageSkillRoutingRule
+} from '../types.js';
+
+const SKILL_CATEGORIES: readonly SkillCategory[] = ['stage-method', 'domain', 'quality-policy'];
+const REPO_CONTEXT_FACTS: readonly RepoContextFact[] = ['language', 'framework', 'project_type', 'architecture_pattern', 'risk_signal'];
+
+function asString(value: unknown, fieldName: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new ProdifyError(`Skill field "${fieldName}" must be a non-empty string.`, {
+      code: 'SKILL_SCHEMA_INVALID'
+    });
+  }
+
+  return value.trim();
+}
+
+function asOptionalStringArray(value: unknown, fieldName: string): string[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    return [];
+  }
+
+  return asStringArray(value, fieldName);
+}
+
+function asStringArray(value: unknown, fieldName: string): string[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new ProdifyError(`Skill field "${fieldName}" must be a non-empty list.`, {
+      code: 'SKILL_SCHEMA_INVALID'
+    });
+  }
+
+  const normalized = value.map((entry) => asString(entry, fieldName));
+  return [...new Set(normalized)].sort((left, right) => left.localeCompare(right));
+}
+
+function asRecord(value: unknown, fieldName: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new ProdifyError(`Skill field "${fieldName}" must be a mapping.`, {
+      code: 'SKILL_SCHEMA_INVALID'
+    });
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function asSkillCategory(value: unknown): SkillCategory {
+  const category = asString(value, 'category') as SkillCategory;
+  if (!SKILL_CATEGORIES.includes(category)) {
+    throw new ProdifyError(`Skill category is invalid: ${category}.`, {
+      code: 'SKILL_SCHEMA_INVALID'
+    });
+  }
+
+  return category;
+}
+
+function asStageList(value: unknown, fieldName: string): FlowStage[] {
+  const stages = asStringArray(value, fieldName) as FlowStage[];
+  for (const stage of stages) {
+    if (!CONTRACT_STAGE_NAMES.includes(stage)) {
+      throw new ProdifyError(`Skill field "${fieldName}" contains unsupported stage "${stage}".`, {
+        code: 'SKILL_SCHEMA_INVALID'
+      });
+    }
+  }
+
+  return stages;
+}
+
+function normalizePredicate(value: unknown, fieldName: string): SkillConditionPredicate {
+  const record = asRecord(value, fieldName);
+  const fact = asString(record.fact, `${fieldName}.fact`) as RepoContextFact;
+  if (!REPO_CONTEXT_FACTS.includes(fact)) {
+    throw new ProdifyError(`Skill condition fact is invalid: ${fact}.`, {
+      code: 'SKILL_SCHEMA_INVALID'
+    });
+  }
+
+  return {
+    fact,
+    includes: asString(record.includes, `${fieldName}.includes`)
+  };
+}
+
+export function normalizeSkillCondition(value: unknown, fieldName: string): SkillCondition {
+  const record = asRecord(value, fieldName);
+  const all = Array.isArray(record.all)
+    ? record.all.map((entry, index) => normalizePredicate(entry, `${fieldName}.all[${index}]`))
+    : [];
+
+  if (all.length === 0) {
+    throw new ProdifyError(`Skill condition "${fieldName}" must declare at least one "all" predicate.`, {
+      code: 'SKILL_SCHEMA_INVALID'
+    });
+  }
+
+  return {
+    all: all.sort((left, right) => `${left.fact}:${left.includes}`.localeCompare(`${right.fact}:${right.includes}`))
+  };
+}
+
+export function validateSkillDefinitionShape(value: unknown): SkillDefinition {
+  const record = asRecord(value, 'skill');
+  return {
+    schema_version: asString(record.schema_version, 'schema_version'),
+    id: asString(record.id, 'id'),
+    name: asString(record.name, 'name'),
+    version: asString(record.version, 'version'),
+    category: asSkillCategory(record.category),
+    description: asString(record.description, 'description'),
+    intended_use: asStringArray(record.intended_use, 'intended_use'),
+    stage_compatibility: asStageList(record.stage_compatibility, 'stage_compatibility'),
+    activation_conditions: Array.isArray(record.activation_conditions)
+      ? record.activation_conditions.map((entry, index) => normalizeSkillCondition(entry, `activation_conditions[${index}]`))
+      : [],
+    execution_guidance: asStringArray(record.execution_guidance, 'execution_guidance'),
+    caution_guidance: asOptionalStringArray(record.caution_guidance, 'caution_guidance')
+  };
+}
+
+export function validateSkillRegistryManifest(value: unknown): SkillRegistryManifest {
+  const record = asRecord(value, 'skill registry');
+  return {
+    schema_version: asString(record.schema_version, 'schema_version'),
+    skills: asStringArray(record.skills, 'skills')
+      .map((entry) => normalizeRepoRelativePath(entry))
+  };
+}
+
+function validateRoutingSkillIds(skillIds: string[], fieldName: string): string[] {
+  return [...new Set(skillIds.map((entry) => asString(entry, fieldName)))].sort((left, right) => left.localeCompare(right));
+}
+
+function normalizeRoutingRule(value: unknown, fieldName: string): StageSkillRoutingRule {
+  const record = asRecord(value, fieldName);
+  return {
+    skill: asString(record.skill, `${fieldName}.skill`),
+    when: normalizeSkillCondition(record.when, `${fieldName}.when`),
+    reason: asString(record.reason, `${fieldName}.reason`)
+  };
+}
+
+export function normalizeStageSkillRouting(value: unknown): StageSkillRouting {
+  if (value === undefined || value === null) {
+    return {
+      default_skills: [],
+      allowed_skills: [],
+      conditional_skills: []
+    };
+  }
+
+  const record = asRecord(value, 'skill_routing');
+  const defaultSkills = Array.isArray(record.default_skills)
+    ? validateRoutingSkillIds(record.default_skills, 'skill_routing.default_skills')
+    : [];
+  const allowedSkills = Array.isArray(record.allowed_skills)
+    ? validateRoutingSkillIds(record.allowed_skills, 'skill_routing.allowed_skills')
+    : [];
+  const conditionalSkills = Array.isArray(record.conditional_skills)
+    ? record.conditional_skills.map((entry, index) => normalizeRoutingRule(entry, `skill_routing.conditional_skills[${index}]`))
+      .sort((left, right) => left.skill.localeCompare(right.skill) || left.reason.localeCompare(right.reason))
+    : [];
+
+  for (const skillId of defaultSkills) {
+    if (!allowedSkills.includes(skillId)) {
+      throw new ProdifyError(`Default skill "${skillId}" must also be listed in allowed_skills.`, {
+        code: 'SKILL_ROUTING_INVALID'
+      });
+    }
+  }
+
+  for (const rule of conditionalSkills) {
+    if (!allowedSkills.includes(rule.skill)) {
+      throw new ProdifyError(`Conditional skill "${rule.skill}" must also be listed in allowed_skills.`, {
+        code: 'SKILL_ROUTING_INVALID'
+      });
+    }
+  }
+
+  return {
+    default_skills: defaultSkills,
+    allowed_skills: allowedSkills,
+    conditional_skills: conditionalSkills
+  };
+}