@unrdf/project-engine 5.0.1

package/src/gap-finder.mjs

@@ -0,0 +1,376 @@
+/**
+ * @file Predictive Gap Finder - analyze domain model + project files to identify missing roles
+ * @module project-engine/gap-finder
+ */
+
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { z } from 'zod';
+
+const { namedNode } = DataFactory;
+
+/* ========================================================================= */
+/* Namespace prefixes                                                        */
+/* ========================================================================= */
+
+const NS = {
+  rdf: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  rdfs: 'http://www.w3.org/2000/01/rdf-schema#',
+  dom: 'http://example.org/unrdf/domain#',
+  fs: 'http://example.org/unrdf/filesystem#',
+  proj: 'http://example.org/unrdf/project#',
+};
+
+/* ========================================================================= */
+/* Zod Schemas                                                               */
+/* ========================================================================= */
+
+const StackProfileSchema = z
+  .object({
+    webFramework: z.string().nullable().optional(),
+    uiFramework: z.string().nullable().optional(),
+    apiFramework: z.string().nullable().optional(),
+    testFramework: z.string().nullable().optional(),
+  })
+  .passthrough()
+  .optional();
+
+const FindMissingRolesOptionsSchema = z.object({
+  domainStore: z.custom(val => val && typeof val.getQuads === 'function', {
+    message: 'domainStore must be an RDF store with getQuads method',
+  }),
+  projectStore: z.custom(val => val && typeof val.getQuads === 'function', {
+    message: 'projectStore must be an RDF store with getQuads method',
+  }),
+  templateGraph: z.custom(val => val && typeof val.getQuads === 'function').optional(),
+  stackProfile: StackProfileSchema,
+});
+
+/* ========================================================================= */
+/* Role configuration                                                        */
+/* ========================================================================= */
+
+/**
+ * Base role importance scores (0-100)
+ */
+const ROLE_BASE_SCORES = {
+  Api: 95,
+  Route: 95,
+  Test: 90,
+  Component: 80,
+  Page: 80,
+  View: 80,
+  Schema: 70,
+  Service: 60,
+  Hook: 55,
+  Doc: 50,
+};
+
+/**
+ * Required roles per framework
+ */
+const FRAMEWORK_ROLES = {
+  next: ['Page', 'Api', 'Component', 'Test', 'Schema'],
+  'next-app-router': ['Page', 'Api', 'Component', 'Test', 'Schema'],
+  'next-pages': ['Page', 'Api', 'Component', 'Test', 'Schema'],
+  express: ['Route', 'Service', 'Test', 'Schema'],
+  nest: ['Controller', 'Service', 'Test', 'Schema'],
+  react: ['Component', 'Test', 'Schema'],
+  default: ['Api', 'Component', 'Test', 'Schema'],
+};
+
+/**
+ * Framework-specific role score boosts
+ */
+const FRAMEWORK_BOOSTS = {
+  next: { Page: 15, Api: 10 },
+  'next-app-router': { Page: 15, Api: 10 },
+  'next-pages': { Page: 15, Api: 10 },
+  express: { Route: 15, Service: 10 },
+  nest: { Controller: 15, Service: 10 },
+};
+
+/* ========================================================================= */
+/* Entity extraction                                                         */
+/* ========================================================================= */
+
+/**
+ * Extract entity names from domain store
+ * @param {Store} domainStore
+ * @returns {string[]}
+ */
+function extractEntities(domainStore) {
+  const entities = [];
+  const quads = domainStore.getQuads(
+    null,
+    namedNode(`${NS.rdf}type`),
+    namedNode(`${NS.dom}Entity`)
+  );
+
+  for (const quad of quads) {
+    const iri = quad.subject.value;
+    const name = iri.split('#').pop() || iri.split('/').pop();
+    if (name) entities.push(name);
+  }
+
+  return entities;
+}
+
+/* ========================================================================= */
+/* File role extraction                                                      */
+/* ========================================================================= */
+
+/**
+ * Extract file paths with their roles from project store
+ * @param {Store} projectStore
+ * @returns {Array<{path: string, role: string|null}>}
+ */
+function extractFilesWithRoles(projectStore) {
+  const files = [];
+
+  const pathQuads = projectStore.getQuads(null, namedNode(`${NS.fs}relativePath`), null);
+
+  for (const quad of pathQuads) {
+    const fileIri = quad.subject;
+    const path = quad.object.value;
+
+    // Get role for this file
+    const roleQuads = projectStore.getQuads(fileIri, namedNode(`${NS.proj}roleString`), null);
+
+    const role = roleQuads.length > 0 ? roleQuads[0].object.value : null;
+    files.push({ path, role });
+  }
+
+  return files;
+}
+
+/* ========================================================================= */
+/* Entity-file matching                                                      */
+/* ========================================================================= */
+
+/**
+ * Match file to entity by name pattern
+ * @param {string} filePath
+ * @param {string} entityName
+ * @returns {boolean}
+ */
+function fileMatchesEntity(filePath, entityName) {
+  const lowerPath = filePath.toLowerCase();
+  const lowerEntity = entityName.toLowerCase();
+
+  // Direct match
+  if (lowerPath.includes(lowerEntity)) return true;
+
+  // Plural form: User -> users
+  if (lowerPath.includes(lowerEntity + 's')) return true;
+
+  // Kebab-case: UserProfile -> user-profile
+  const kebabEntity = entityName.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+  if (lowerPath.includes(kebabEntity)) return true;
+
+  // Snake_case: UserProfile -> user_profile
+  const snakeEntity = entityName.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+  if (lowerPath.includes(snakeEntity)) return true;
+
+  return false;
+}
+
+/**
+ * Find roles present for an entity
+ * @param {string} entityName
+ * @param {Array<{path: string, role: string|null}>} files
+ * @returns {Set<string>}
+ */
+function findPresentRoles(entityName, files) {
+  const roles = new Set();
+
+  for (const { path, role } of files) {
+    if (role && fileMatchesEntity(path, entityName)) {
+      roles.add(role);
+    }
+  }
+
+  return roles;
+}
+
+/* ========================================================================= */
+/* Gap detection                                                             */
+/* ========================================================================= */
+
+/**
+ * Determine required roles based on stack profile
+ * @param {Object} stackProfile
+ * @returns {string[]}
+ */
+function getRequiredRoles(stackProfile) {
+  if (!stackProfile) return FRAMEWORK_ROLES.default;
+
+  const framework = stackProfile.webFramework || stackProfile.apiFramework;
+  if (framework && FRAMEWORK_ROLES[framework]) {
+    return FRAMEWORK_ROLES[framework];
+  }
+
+  return FRAMEWORK_ROLES.default;
+}
+
+/**
+ * Calculate missing roles for an entity
+ * @param {string} entityName
+ * @param {Set<string>} presentRoles
+ * @param {string[]} requiredRoles
+ * @returns {string[]}
+ */
+function calculateMissingRoles(entityName, presentRoles, requiredRoles) {
+  return requiredRoles.filter(role => !presentRoles.has(role));
+}
+
+/**
+ * Generate suggestion for a missing role
+ * @param {string} entityName
+ * @param {string} role
+ * @returns {string}
+ */
+function generateSuggestion(entityName, role) {
+  const suggestions = {
+    Api: `${entityName}Api is needed for /${entityName.toLowerCase()} endpoint`,
+    Route: `${entityName}Route handler needed for /${entityName.toLowerCase()} routes`,
+    Page: `${entityName}Page needed for /${entityName.toLowerCase()} view`,
+    Component: `${entityName}View component needed for UI`,
+    Test: `${entityName} test suite needed for coverage`,
+    Schema: `${entityName}Schema needed for validation`,
+    Service: `${entityName}Service needed for business logic`,
+    Doc: `${entityName} documentation needed`,
+  };
+
+  return suggestions[role] || `${entityName}${role} needed`;
+}
+
+/* ========================================================================= */
+/* Main API                                                                  */
+/* ========================================================================= */
+
+/**
+ * @typedef {Object} GapResult
+ * @property {string} entity - Entity name
+ * @property {string[]} missingRoles - Roles that are missing
+ * @property {number} score - Priority score (0-100)
+ * @property {string} suggestion - Human-readable suggestion
+ * @property {string[]} [files] - Related files if they exist but aren't classified
+ */
+
+/**
+ * @typedef {Object} FindMissingRolesResult
+ * @property {GapResult[]} gaps - Array of gap results
+ * @property {string} summary - Human-readable summary
+ * @property {string} callToAction - CLI command suggestion
+ */
+
+/**
+ * Analyze domain model + project files to predict which features are missing roles
+ *
+ * @param {Object} options
+ * @param {Store} options.domainStore - Domain model store (from inferDomainModel)
+ * @param {Store} options.projectStore - Project structure store (from buildProjectModelFromFs + classifyFiles)
+ * @param {Store} [options.templateGraph] - Optional template graph
+ * @param {Object} [options.stackProfile] - Stack profile for framework-specific rules
+ * @returns {FindMissingRolesResult}
+ */
+export function findMissingRoles(options) {
+  const validated = FindMissingRolesOptionsSchema.parse(options);
+  const { domainStore, projectStore, stackProfile } = validated;
+
+  // Extract entities from domain model
+  const entities = extractEntities(domainStore);
+
+  // Early exit if no entities
+  if (entities.length === 0) {
+    return {
+      gaps: [],
+      summary: '0 gaps found (no entities in domain model)',
+      callToAction: 'Run: unrdf infer-domain to detect domain entities',
+    };
+  }
+
+  // Extract files with roles from project store
+  const files = extractFilesWithRoles(projectStore);
+
+  // Determine required roles based on stack
+  const requiredRoles = getRequiredRoles(stackProfile);
+
+  // Find gaps for each entity
+  const gaps = [];
+  const gapCounts = { Api: 0, Test: 0, Component: 0, Schema: 0, other: 0 };
+
+  for (const entityName of entities) {
+    const presentRoles = findPresentRoles(entityName, files);
+    const missingRoles = calculateMissingRoles(entityName, presentRoles, requiredRoles);
+
+    // Calculate max score for this entity's gaps
+    const maxScore = missingRoles.reduce((max, role) => {
+      const score = scoreMissingRole(entityName, role, stackProfile || {});
+      return Math.max(max, score);
+    }, 0);
+
+    // Count gaps by type
+    for (const role of missingRoles) {
+      if (gapCounts[role] !== undefined) {
+        gapCounts[role]++;
+      } else {
+        gapCounts.other++;
+      }
+    }
+
+    gaps.push({
+      entity: entityName,
+      missingRoles,
+      score: maxScore,
+      suggestion: missingRoles.length > 0 ? generateSuggestion(entityName, missingRoles[0]) : '',
+    });
+  }
+
+  // Sort by score (highest first)
+  gaps.sort((a, b) => b.score - a.score);
+
+  // Generate summary
+  const summaryParts = [];
+  if (gapCounts.Api > 0) summaryParts.push(`${gapCounts.Api} missing APIs`);
+  if (gapCounts.Test > 0) summaryParts.push(`${gapCounts.Test} missing tests`);
+  if (gapCounts.Component > 0) summaryParts.push(`${gapCounts.Component} missing components`);
+  if (gapCounts.Schema > 0) summaryParts.push(`${gapCounts.Schema} missing schemas`);
+  if (gapCounts.other > 0) summaryParts.push(`${gapCounts.other} other gaps`);
+
+  const summary =
+    summaryParts.length > 0
+      ? summaryParts.join(', ')
+      : '0 gaps found - all entities have required roles';
+
+  // Generate call to action
+  const topGap = gaps.find(g => g.missingRoles.length > 0);
+  const callToAction = topGap
+    ? `Run: unrdf generate --entity ${topGap.entity} --roles ${topGap.missingRoles.join(',')}`
+    : 'Run: unrdf analyze to check for other issues';
+
+  return { gaps, summary, callToAction };
+}
+
+/**
+ * Score the importance of a missing role for an entity
+ *
+ * @param {string} entity - Entity name
+ * @param {string} role - Missing role name
+ * @param {Object} stackProfile - Stack profile for framework-specific boosts
+ * @returns {number} Score from 0-100
+ */
+export function scoreMissingRole(entity, role, stackProfile) {
+  // Get base score
+  let score = ROLE_BASE_SCORES[role] || 40;
+
+  // Apply framework-specific boosts
+  const framework = stackProfile?.webFramework || stackProfile?.apiFramework;
+  if (framework && FRAMEWORK_BOOSTS[framework]) {
+    const boost = FRAMEWORK_BOOSTS[framework][role] || 0;
+    score += boost;
+  }
+
+  // Cap at 100
+  return Math.min(score, 100);
+}

package/src/golden-structure.mjs

@@ -0,0 +1,149 @@
+/**
+ * @file Golden structure ontologies - canonical best-practice structures
+ * @module project-engine/golden-structure
+ */
+
+import { promises as _fs } from 'fs';
+import { createStore as _createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
+import { parseTurtle } from '../knowledge-engine/parse.mjs';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { z } from 'zod';
+
+const tracer = trace.getTracer('unrdf/golden-structure');
+
+const GoldenStructureOptionsSchema = z.object({
+  profile: z.enum([
+    'react-feature-v1',
+    'next-app-router-v1',
+    'next-pages-v1',
+    'nest-api-v1',
+    'express-api-v1',
+  ]),
+});
+
+/**
+ * Generate or load golden structure from profile
+ *
+ * @param {Object} options
+ * @param {string} options.profile - Profile ID (e.g., 'react-feature-v1')
+ * @returns {Promise<Store>} Store with golden structure
+ */
+export async function generateGoldenStructure(options) {
+  const validated = GoldenStructureOptionsSchema.parse(options);
+  const { profile } = validated;
+
+  return tracer.startActiveSpan('golden.structure.generate', async span => {
+    try {
+      span.setAttribute('golden.profile', profile);
+
+      const ttl = getGoldenStructureTtl(profile);
+      const store = await parseTurtle(ttl, 'http://example.org/unrdf/golden#');
+
+      span.setAttribute('golden.store_size', store.size);
+      span.setStatus({ code: SpanStatusCode.OK });
+
+      return store;
+    } catch (error) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+      throw error;
+    }
+  });
+}
+
+/**
+ * Get golden structure TTL for a profile
+ *
+ * @private
+ */
+function getGoldenStructureTtl(profile) {
+  const baseGolden = `
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix unproj: <http://example.org/unrdf/project#> .
+@prefix golden: <http://example.org/unrdf/golden#> .
+
+golden:project a unproj:Project ;
+  rdfs:label "Golden Structure" .
+`;
+
+  // Profile-specific structures
+  if (profile === 'react-feature-v1') {
+    return (
+      baseGolden +
+      `
+golden:featureExample a unproj:Feature ;
+  rdfs:label "Example Feature" ;
+  rdfs:comment "Standard React feature structure" .
+
+golden:featureExample unproj:hasRole unproj:Component ;
+  unproj:hasRole unproj:Hook ;
+  unproj:hasRole unproj:Schema ;
+  unproj:hasRole unproj:Test ;
+  unproj:hasRole unproj:Doc .
+
+golden:pathComponentPattern a rdf:Property ;
+  rdfs:value "src/features/*/components/*.tsx" .
+
+golden:pathHookPattern a rdf:Property ;
+  rdfs:value "src/features/*/hooks/use*.ts" .
+
+golden:pathTestPattern a rdf:Property ;
+  rdfs:value "src/features/**/*.test.tsx" .
+`
+    );
+  } else if (profile === 'next-app-router-v1') {
+    return (
+      baseGolden +
+      `
+golden:project unproj:webFramework "next-app-router" .
+
+golden:pageExample a unproj:Page ;
+  rdfs:label "Page Route" .
+
+golden:layoutExample a unproj:Component ;
+  rdfs:label "Layout Component" .
+
+golden:apiExample a unproj:Api ;
+  rdfs:label "API Route" .
+
+golden:pathPagePattern a rdf:Property ;
+  rdfs:value "src/app/**/page.tsx" .
+
+golden:pathLayoutPattern a rdf:Property ;
+  rdfs:value "src/app/**/layout.tsx" .
+
+golden:pathApiPattern a rdf:Property ;
+  rdfs:value "src/app/**/route.ts" .
+`
+    );
+  } else if (profile === 'nest-api-v1') {
+    return (
+      baseGolden +
+      `
+golden:project unproj:webFramework "nest" ;
+  unproj:apiFramework "nest" .
+
+golden:controllerExample a unproj:Api ;
+  rdfs:label "NestJS Controller" .
+
+golden:serviceExample a unproj:Service ;
+  rdfs:label "NestJS Service" .
+
+golden:schemaExample a unproj:Schema ;
+  rdfs:label "NestJS DTO" .
+
+golden:pathControllerPattern a rdf:Property ;
+  rdfs:value "src/**/*.controller.ts" .
+
+golden:pathServicePattern a rdf:Property ;
+  rdfs:value "src/**/*.service.ts" .
+
+golden:pathDtoPattern a rdf:Property ;
+  rdfs:value "src/**/dto/*.dto.ts" .
+`
+    );
+  } else {
+    // Default fallback
+    return baseGolden;
+  }
+}