import fs from 'node:fs'; import path from 'node:path'; const projectRoot = process.cwd(); const srcDir = path.join(projectRoot, 'src'); const specPath = path.join(projectRoot, 'BACKEND_SPEC.md'); console.log('===================================================='); console.log(' HABIB SHOP - BACKEND SPECIFICATION AUDITOR'); console.log('====================================================\n'); // 1. Check existence of BACKEND_SPEC.md if (!fs.existsSync(specPath)) { console.error(`FATAL: ${specPath} does not exist!`); process.exit(1); } const specContent = fs.readFileSync(specPath, 'utf8'); const specLines = specContent.split('\n'); console.log(`Loaded BACKEND_SPEC.md: ${specLines.length} lines, ${Buffer.byteLength(specContent, 'utf8')} bytes.\n`); let totalErrors = 0; // 2. Programmatically scan all files in src/ and check 100% citation function walkDir(dir) { const entries = fs.readdirSync(dir, { withFileTypes: true }); const files = []; for (const entry of entries) { const full = path.join(dir, entry.name); if (entry.isDirectory()) { files.push(...walkDir(full)); } else if (entry.isFile()) { files.push(full); } } return files; } const allSrcFiles = walkDir(srcDir).map((f) => { const rel = path.relative(projectRoot, f).replace(/\\/g, '/'); return rel; }); console.log(`Found ${allSrcFiles.length} total source/asset files in src/.\nVerifying 100% citation in BACKEND_SPEC.md...`); let missingFileCount = 0; for (const relFile of allSrcFiles) { if (!specContent.includes(relFile)) { console.error(` [MISSING CITATION]: "${relFile}" is not cited in BACKEND_SPEC.md`); missingFileCount++; totalErrors++; } } if (missingFileCount === 0) { console.log(` PASS: All ${allSrcFiles.length} files in src/ are 100% cited and mapped.\n`); } else { console.error(` FAIL: ${missingFileCount} files are missing citations!\n`); } // 3. Check for unresolved placeholders: TODO, TBD, and ellipsis truncations in code blocks console.log('Verifying absence of unresolved placeholders (TODO, TBD, ... truncations)...'); const todoRegex = /\bTODO\b/g; const tbdRegex = /\bTBD\b/g; let placeholderMatches = 0; let match; while ((match = todoRegex.exec(specContent)) !== null) { const lineNo = specContent.slice(0, match.index).split('\n').length; console.error(` [PLACEHOLDER FOUND]: "TODO" at line ${lineNo}`); placeholderMatches++; totalErrors++; } while ((match = tbdRegex.exec(specContent)) !== null) { const lineNo = specContent.slice(0, match.index).split('\n').length; console.error(` [PLACEHOLDER FOUND]: "TBD" at line ${lineNo}`); placeholderMatches++; totalErrors++; } // Check for lazy ellipsis truncation in JSON / code blocks let inCodeBlock = false; let codeBlockEllipsis = 0; for (let i = 0; i < specLines.length; i++) { const line = specLines[i]; if (line.trim().startsWith('```')) { inCodeBlock = !inCodeBlock; continue; } if (inCodeBlock) { const trimmed = line.trim(); if (trimmed === '...' || trimmed === '...,' || trimmed === '{...}' || trimmed === '[...]') { console.error(` [LAZY ELLIPSIS TRUNCATION]: "${trimmed}" at line ${i + 1}`); codeBlockEllipsis++; totalErrors++; } } } if (placeholderMatches === 0 && codeBlockEllipsis === 0) { console.log(' PASS: Zero placeholders (TODO, TBD) and zero code-block ellipsis truncations found.\n'); } else { console.error(` FAIL: Found ${placeholderMatches} placeholders and ${codeBlockEllipsis} code-block ellipsis truncations!\n`); } // 4. Verify canonical entities (all 20 canonical entities) console.log('Verifying presence of 20 canonical entity models and database tables...'); const requiredEntities = [ 'users', 'user_addresses', 'store_booths', 'categories', 'products', 'product_gallery_images', 'wishlist_bookmarks', 'shopping_carts', 'cart_items', 'orders', 'order_shipments', 'order_shipment_items', 'support_tickets', 'support_ticket_attachments', 'chat_conversations', 'chat_messages', 'provider_applications', 'habib_coin_transactions', 'marketing_banners', 'donation_campaigns', ]; let missingEntities = 0; for (const entity of requiredEntities) { const ddlRegex = new RegExp(`CREATE\\s+TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${entity}\\b`, 'i'); if (!ddlRegex.test(specContent)) { console.error(` [MISSING DDL TABLE]: "CREATE TABLE ${entity}" not found in specification`); missingEntities++; totalErrors++; } } if (missingEntities === 0) { console.log(` PASS: All ${requiredEntities.length} canonical entities have valid CREATE TABLE DDL statements.\n`); } else { console.error(` FAIL: ${missingEntities} canonical entities missing DDL statements!\n`); } // 5. Verify REST endpoints count and schema definitions console.log('Verifying REST API endpoints coverage...'); const endpointRegex = /### Endpoint \d+: `(GET|POST|PUT|PATCH|DELETE) (\/api\/v1\/[a-zA-Z0-9_\-/{}]*)`/g; const endpointsFound = []; let epMatch; while ((epMatch = endpointRegex.exec(specContent)) !== null) { endpointsFound.push({ method: epMatch[1], path: epMatch[2] }); } console.log(`Detected ${endpointsFound.length} fully structured REST endpoint contracts.`); if (endpointsFound.length >= 62) { console.log(` PASS: Required endpoint threshold met (${endpointsFound.length} >= 62).\n`); } else { console.error(` FAIL: Found only ${endpointsFound.length} endpoints, expected at least 62!\n`); totalErrors++; } // 6. Verify Section 3.2.1 Mock Data Field Discard & Presentation Reconciliation Table console.log('Verifying Section 3.2.1 Mock Data Field Discard & Presentation Reconciliation Table...'); const discardTablePresent = specContent.includes('3.2.1 Mock Data Field Discard & Presentation Reconciliation Table'); const keyTokens = [ 'relX', 'relY', 'labelLeft', 'labelWidth', 'originRelY', 'ratingPillWidth', 'titleHeight', 'badgeLeft', 'bgColor', 'titleColor', 'subtitleWidth', 'iconBoxBg', 'badgeCount', 'rightIconType', 'gradientBg', 'figmaNodeId', ]; let missingTokens = 0; for (const token of keyTokens) { if (!specContent.includes(`\`${token}\``)) { console.error(` [MISSING DISCARD TOKEN]: "${token}" is not documented in the discard table`); missingTokens++; totalErrors++; } } if (discardTablePresent && missingTokens === 0) { console.log(` PASS: Section 3.2.1 Discard Table is present and documents all ${keyTokens.length} verified layout tokens.\n`); } else { console.error(' FAIL: Discard table is missing or incomplete!\n'); totalErrors++; } // 7. Verify Section 3.5 Technology-Agnostic JSON Schemas for ALL 20 Canonical Entities console.log('Verifying Section 3.5 Draft-07 JSON Schemas for ALL 20 canonical entities...'); const sec35Match = specContent.match(/###\s*3\.5\s+Technology-Agnostic\s+JSON\s+Schemas[\s\S]*?(?=##\s*4\.\s*REST|$)/); if (!sec35Match) { console.error(' [FATAL]: Section 3.5 not found in specification!'); totalErrors++; } else { const sec35Content = sec35Match[0]; let missingSchemas = 0; for (const entity of requiredEntities) { const schemaHeadingRegex = new RegExp(`####\\s*\\d+\\.[^\\n]*\\(${entity}\\)`, 'i'); if (!schemaHeadingRegex.test(sec35Content)) { console.error(` [MISSING JSON SCHEMA]: Dedicated schema heading for "${entity}" not found in Section 3.5`); missingSchemas++; totalErrors++; } } if (missingSchemas === 0) { console.log(` PASS: All ${requiredEntities.length} canonical entities have dedicated Draft-07 JSON Schemas in Section 3.5.\n`); } else { console.error(` FAIL: ${missingSchemas} entity JSON Schemas are missing from Section 3.5!\n`); } } // 8. Programmatic Validation of ALL fenced JSON code blocks console.log('Validating syntax of ALL fenced JSON code blocks across BACKEND_SPEC.md...'); const jsonBlockRegex = /```json\s*([\s\S]*?)```/g; let jsonBlockMatch; let jsonBlockCount = 0; let jsonBlockErrors = 0; while ((jsonBlockMatch = jsonBlockRegex.exec(specContent)) !== null) { jsonBlockCount++; const rawJson = jsonBlockMatch[1]; try { JSON.parse(rawJson); } catch (err) { console.error(` [INVALID JSON BLOCK #${jsonBlockCount}]: ${err.message}`); jsonBlockErrors++; totalErrors++; } } if (jsonBlockErrors === 0) { console.log(` PASS: All ${jsonBlockCount} fenced JSON code blocks parsed successfully with 0 syntax errors.\n`); } else { console.error(` FAIL: Found ${jsonBlockErrors} invalid JSON code blocks!\n`); } // 9. Verify PostgreSQL DDL constraints & error envelope console.log('Verifying database constraints & error envelopes...'); const uniqueCartConstraint = specContent.includes('CONSTRAINT uq_shopping_carts_user UNIQUE (user_id)'); const addressSnapshotPresent = specContent.includes('shipping_address_snapshot'); const errorEnvelopePresent = specContent.includes('Standard Error Response') && specContent.includes('RESOURCE_NOT_FOUND'); if (uniqueCartConstraint && addressSnapshotPresent && errorEnvelopePresent) { console.log(' PASS: Unique cart constraint, address snapshotting, and error envelopes are verified.\n'); } else { console.error(' FAIL: Missing critical constraint or error envelope definitions!\n'); totalErrors++; } // Final Summary console.log('===================================================='); if (totalErrors === 0) { console.log(' RESULT: ALL QUALITY GATES PASSED (100% COMPLIANT)'); console.log('===================================================='); process.exit(0); } else { console.error(` RESULT: FAILED WITH ${totalErrors} ERROR(S)`); console.log('===================================================='); process.exit(1); }