SIDDARTHA577/envguard-node / .agents/skills/envguard-mobile-readiness
envguard-mobile-readiness
VerifiedGuides comprehensive, evidence-based mobile application readiness assessments for React Native, Expo, Flutter, Native Android (Kotlin/Java), and Native iOS (Swift) aligned with OWASP MASVS v2.0 standards.
scripts/readiness/reporters/markdown-reporter.mjs
View on GitHubimport { escapeMarkdown } from '../constants.mjs';
import { formatArchitectureMarkdown } from '../architecture/architecture-reporter.mjs';
/**
* Generates human-readable Markdown readiness report with standardized executive summary,
* finding breakdowns, prioritized remediations, and architecture review.
* Preserves backwards compatibility with existing test suites.
*/
export function generateMarkdownReport(report) {
const { summary, findings, limitations, configuration, platform, projectRoot, timestamp } = report;
let md = `# EnvGuard Production Readiness Assessment Report\n\n`;
md += `**Project**: \`${escapeMarkdown(projectRoot)}\` \n`;
md += `**Timestamp**: ${timestamp} \n`;
md += `**Auditor Version**: v${report.toolVersion} (Schema v${report.schemaVersion}) \n`;
md += `**Platform**: Node.js ${platform.nodeVersion} on ${platform.os} \n`;
md += `**Execution Permitted (--allow-exec)**: ${configuration.allowExec ? 'Yes (Authorized Mode)' : 'No (Read-Only Mode)'} \n`;
if (configuration.allowExec) {
md += `**Execution Containment**: ${report.executionPolicy?.isolated ? 'Container Isolated' : configuration.trustProject ? 'Host Explicitly Trusted (--trust-project)' : 'Untrusted Blocked'} \n`;
}
if (report.policyEvaluation?.outcome) {
md += `**Release Gate Outcome**: \`${report.policyEvaluation.outcome}\` \n`;
}
md += `\n`;
// Executive Summary Table
md += `## 1. Executive Summary\n\n`;
md += `| Check Status | Count | Description |\n`;
md += `| :--- | :---: | :--- |\n`;
md += `| **PASS** | ${summary.pass} | Verified passing criteria |\n`;
md += `| **FAIL** | ${summary.fail} | Blocking failures requiring remediation |\n`;
md += `| **WARNING** | ${summary.warning} | Non-blocking risks or missing conventions |\n`;
md += `| **INFORMATIONAL** | ${summary.informational ?? 0} | Informational diagnostics and external notes |\n`;
md += `| **NOT_RUN** | ${summary.notRun} | Checks skipped (authorization or infra unavailable) |\n`;
md += `| **MANUAL_REVIEW** | ${summary.manualReview} | Heuristics requiring human engineering review |\n`;
md += `| **NOT_APPLICABLE**| ${summary.notApplicable} | Checks irrelevant to detected project type |\n`;
md += `| **Total Checks** | ${summary.totalChecks} | Comprehensive assessment scope |\n\n`;
// Discovered Inventory & Architecture (if multi-application or monorepo)
if (report.projectMetadata?.inventory?.applications?.length > 1) {
const apps = report.projectMetadata.inventory.applications;
md += `### Discovered Architecture & Workspaces (${apps.length} applications)\n\n`;
md += `| Application | Path | Type | Frameworks | Databases |\n`;
md += `| :--- | :--- | :--- | :--- | :--- |\n`;
for (const app of apps) {
md += `| \`${escapeMarkdown(app.name)}\` | \`${escapeMarkdown(app.path)}\` | ${app.type} | ${app.frameworks?.join(', ') || 'none'} | ${app.databases?.join(', ') || 'none'} |\n`;
}
md += `\n`;
}
// 2. Blocking Failures
const failures = findings.filter((f) => f.status === 'FAIL');
if (failures.length > 0) {
md += `## 2. Blocking Failures (${failures.length})\n\n`;
for (const f of failures) {
md += `### [${f.id}] ${escapeMarkdown(f.title)}\n`;
md += `- **Severity**: \`${f.severity ? f.severity.toUpperCase() : 'BLOCKER'}\` | **Confidence**: \`${f.confidence}\`\n`;
md += `- **Explanation**: ${escapeMarkdown(f.explanation)}\n`;
if (f.evidence?.file) md += `- **Evidence**: \`${escapeMarkdown(f.evidence.file)}\`\n`;
if (f.evidence?.command) md += `- **Command**: \`${escapeMarkdown(f.evidence.command)}\` (exit code: ${f.evidence.exitCode})\n`;
if (f.evidence?.snippet) md += `\`\`\`\n${escapeMarkdown(f.evidence.snippet)}\n\`\`\`\n`;
md += `- **Recommendation**: ${escapeMarkdown(f.recommendation)}\n\n`;
}
}
// 3. Warnings
const warnings = findings.filter((f) => f.status === 'WARNING');
if (warnings.length > 0) {
md += `## 3. Warnings & Improvement Opportunities (${warnings.length})\n\n`;
for (const w of warnings) {
md += `### [${w.id}] ${escapeMarkdown(w.title)}\n`;
md += `- **Explanation**: ${escapeMarkdown(w.explanation)}\n`;
if (w.evidence?.file) md += `- **Evidence**: \`${escapeMarkdown(w.evidence.file)}\`\n`;
md += `- **Recommendation**: ${escapeMarkdown(w.recommendation)}\n\n`;
}
}
// 4. Verified Passing Checks
const passed = findings.filter((f) => f.status === 'PASS');
md += `## 4. Verified Passing Checks (${passed.length})\n\n`;
for (const p of passed) {
md += `- **[${p.id}] ${escapeMarkdown(p.title)}**: ${escapeMarkdown(p.explanation)}\n`;
}
md += `\n`;
// 5. Manual Review & Not-Run
const manualAndNotRun = findings.filter((f) => f.status === 'MANUAL_REVIEW' || f.status === 'NOT_RUN');
if (manualAndNotRun.length > 0) {
md += `## 5. Unexecuted & Manual Review Items (${manualAndNotRun.length})\n\n`;
for (const item of manualAndNotRun) {
md += `- **[${item.id}] ${escapeMarkdown(item.title)}** (${item.status}): ${escapeMarkdown(item.explanation)}\n`;
}
md += `\n`;
}
// 5b. Informational Diagnostics
const informational = findings.filter((f) => f.status === 'INFORMATIONAL');
if (informational.length > 0) {
md += `## Informational Diagnostics (${informational.length})\n\n`;
for (const info of informational) {
md += `- **[${info.id}] ${escapeMarkdown(info.title)}**: ${escapeMarkdown(info.explanation)}\n`;
}
md += `\n`;
}
// 6. Prioritized Remediation Plan
md += `## 6. Prioritized Remediation Plan\n\n`;
let step = 1;
for (const f of failures) {
md += `${step++}. **[P0 - Blocker]** ${escapeMarkdown(f.title)}: ${escapeMarkdown(f.recommendation)}\n`;
}
for (const w of warnings.filter((w) => w.severity === 'high')) {
md += `${step++}. **[P1 - High]** ${escapeMarkdown(w.title)}: ${escapeMarkdown(w.recommendation)}\n`;
}
for (const w of warnings.filter((w) => w.severity !== 'high')) {
md += `${step++}. **[P2 - Medium/Low]** ${escapeMarkdown(w.title)}: ${escapeMarkdown(w.recommendation)}\n`;
}
if (failures.length === 0 && warnings.length === 0) {
md += `All automated checks passed cleanly! Proceed with manual operational verification before production rollout.\n`;
}
md += `\n`;
// 7. Known Limitations
md += `## 7. Known Limitations & Scope Boundaries\n\n`;
for (const lim of limitations) {
md += `- ${escapeMarkdown(lim)}\n`;
}
md += `\n`;
// 8. Architecture Review & ADRs
if (report.architecture) {
md += formatArchitectureMarkdown(report.architecture);
}
// 9. Comprehensive 12-Domain Engineering Breakdown
md += format12DomainSections(report);
return md;
}
/**
* Generates the standardized 12-section professional engineering report.
* Conforms directly to Phase 8 Section 8.5 requirements.
*
* @param {object} report - Full readiness audit report object
* @returns {string} Professional Markdown report
*/
export function generateProfessionalEngineeringReport(report) {
const { summary, findings, limitations, configuration, platform, projectRoot, timestamp, architecture, policyEvaluation } = report;
let md = `# EnvGuard Professional Engineering Assessment Report\n\n`;
md += `> **Standard**: EnvGuard Evidence-Based Production Readiness Framework (v${report.toolVersion})\n`;
md += `> **Project**: \`${escapeMarkdown(projectRoot)}\` | **Timestamp**: ${timestamp} | **Schema**: v${report.schemaVersion}\n\n`;
// 1. Project Overview & Topology
md += `## 1. Project Overview & Topology\n\n`;
md += `- **Project Root**: \`${escapeMarkdown(projectRoot)}\`\n`;
md += `- **Git Commit**: \`${report.gitCommit || 'unversioned'}\`\n`;
md += `- **Execution Platform**: Node.js ${platform.nodeVersion} on ${platform.os} (${platform.arch})\n`;
md += `- **Execution Authorization**: ${configuration.allowExec ? 'Authorized (`--allow-exec`)' : 'Read-Only Mode'}\n`;
md += `- **Containment**: ${report.executionPolicy?.isolated ? 'Container Isolated' : configuration.trustProject ? 'Host Explicitly Trusted (`--trust-project`)' : 'Untrusted Host Guarded'}\n\n`;
const apps = report.projectMetadata?.inventory?.applications || [];
if (apps.length > 0) {
md += `### Discovered Applications & Workspaces (${apps.length})\n\n`;
md += `| Application | Path | Type | Frameworks | Databases | Adapters |\n`;
md += `| :--- | :--- | :--- | :--- | :--- | :--- |\n`;
for (const app of apps) {
md += `| \`${escapeMarkdown(app.name)}\` | \`${escapeMarkdown(app.path)}\` | ${app.type} | ${app.frameworks?.join(', ') || 'none'} | ${app.databases?.join(', ') || 'none'} | ${app.detectedAdapters?.join(', ') || 'generic'} |\n`;
}
md += `\n`;
}
md += `### Summary Metrics\n\n`;
md += `| Status | Verified Checks | Percentage of Scope |\n`;
md += `| :--- | :---: | :---: |\n`;
md += `| **PASS** | ${summary.pass} | ${summary.totalChecks > 0 ? Math.round((summary.pass / summary.totalChecks) * 100) : 0}% |\n`;
md += `| **FAIL** | ${summary.fail} | ${summary.totalChecks > 0 ? Math.round((summary.fail / summary.totalChecks) * 100) : 0}% |\n`;
md += `| **WARNING** | ${summary.warning} | ${summary.totalChecks > 0 ? Math.round((summary.warning / summary.totalChecks) * 100) : 0}% |\n`;
md += `| **NOT_RUN** | ${summary.notRun} | - |\n`;
md += `| **MANUAL_REVIEW** | ${summary.manualReview} | - |\n`;
md += `| **Total Evaluated** | ${summary.totalChecks} | 100% |\n\n`;
// 2. Architecture & System Design
md += `## 2. Architecture & System Design\n\n`;
if (architecture?.inventory) {
md += `- **Topology Classification**: \`${architecture.inventory.topologyType}\`\n`;
md += `- **Services & Clients**: ${architecture.inventory.counts.services} service(s), ${architecture.inventory.counts.clients} client(s)\n`;
md += `- **Datastores & Queues**: ${architecture.inventory.counts.datastores} datastore(s), ${architecture.inventory.counts.queues} queue(s)\n\n`;
} else {
md += `Architecture inventory evaluated under standard modular application profile.\n\n`;
}
if (architecture?.evaluations?.length > 0) {
md += `### Evaluated System Design Concepts\n\n`;
md += `| Concept | Status | Operational Overhead | Recommendation Summary |\n`;
md += `| :--- | :---: | :---: | :--- |\n`;
for (const item of architecture.evaluations) {
const summaryText = (item.applicability?.reason || item.problemSolved || '').slice(0, 75);
md += `| **${item.name}** | \`${item.status}\` | ${item.operationalOverhead || 'medium'} | ${escapeMarkdown(summaryText)}... |\n`;
}
md += `\n`;
}
// 3. Code Quality & Test Coverage
md += `## 3. Code Quality & Test Coverage\n\n`;
const codeFindings = findings.filter((f) => f.category === 'build_test');
if (codeFindings.length === 0) {
md += `No build or test discrepancies detected in active scope.\n\n`;
} else {
for (const f of codeFindings) {
md += `- **[${f.id}] ${escapeMarkdown(f.title)}** (\`${f.status}\`): ${escapeMarkdown(f.explanation)}\n`;
}
md += `\n`;
}
// 4. Security Posture & Secrets Management
md += `## 4. Security Posture & Secrets Management\n\n`;
const secFindings = findings.filter((f) => f.category === 'security' || f.category === 'env');
if (secFindings.length === 0) {
md += `Zero security policy blockers identified. Standard environment boundaries verified.\n\n`;
} else {
for (const f of secFindings) {
md += `- **[${f.id}] ${escapeMarkdown(f.title)}** (\`${f.status}\`, severity: \`${f.severity || 'medium'}\`): ${escapeMarkdown(f.explanation)}\n`;
}
md += `\n`;
}
// 5. Database Persistence & Migrations
md += `## 5. Database Persistence & Migrations\n\n`;
const dbFindings = findings.filter((f) => f.category === 'database');
if (dbFindings.length === 0) {
md += `No database schema or migration risks identified.\n\n`;
} else {
for (const f of dbFindings) {
md += `- **[${f.id}] ${escapeMarkdown(f.title)}** (\`${f.status}\`): ${escapeMarkdown(f.explanation)}\n`;
}
md += `\n`;
}
// 6. Frontend, UI & Accessibility
md += `## 6. Frontend, UI & Accessibility\n\n`;
const uiFindings = findings.filter((f) => f.category === 'accessibility');
if (uiFindings.length === 0) {
md += `Frontend accessibility and client-boundary checks verified.\n\n`;
} else {
for (const f of uiFindings) {
md += `- **[${f.id}] ${escapeMarkdown(f.title)}** (\`${f.status}\`): ${escapeMarkdown(f.explanation)}\n`;
}
md += `\n`;
}
// 7. Mobile Engineering Readiness
md += `## 7. Mobile Engineering Readiness\n\n`;
const mobileFindings = findings.filter((f) => f.adapterId?.includes('mobile') || f.adapterId?.includes('react-native') || f.adapterId?.includes('flutter') || f.adapterId?.includes('android') || f.adapterId?.includes('ios'));
if (mobileFindings.length === 0) {
md += `No dedicated mobile target applications identified in this repository.\n\n`;
} else {
for (const f of mobileFindings) {
md += `- **[${f.id}] ${escapeMarkdown(f.title)}** (\`${f.status}\`): ${escapeMarkdown(f.explanation)}\n`;
}
md += `\n`;
}
// 8. Performance & Capacity Modeling
md += `## 8. Performance & Capacity Modeling\n\n`;
if (architecture?.capacityModel) {
const cap = architecture.capacityModel;
md += `- **Workload State**: \`${cap.workloadState}\`\n`;
md += `- **Result Provenance Category**: \`${cap.category || 'ILLUSTRATIVE_SCENARIO'}\`\n`;
md += `- **Projected 10k-VU Peak Throughput**: ${cap.hypothetical10kScenario?.parameters?.projectedPeakRps || 1500} req/s\n`;
md += `- **Recommended Compute Replicas**: ${cap.resourceProjections?.recommendedComputeReplicas || 5} instances\n\n`;
} else {
md += `Standard performance baseline verified without dedicated load profiling.\n\n`;
}
// 9. Reliability, Resilience & Failure Modes
md += `## 9. Reliability, Resilience & Failure Modes\n\n`;
if (architecture?.failureModes?.length > 0) {
md += `### Failure Modes & Effects Analysis (FMEA)\n\n`;
for (const fm of architecture.failureModes.slice(0, 5)) {
md += `- **${fm.name}**: Impact rated \`${fm.impact}\`. Mitigation: ${escapeMarkdown(fm.mitigation)}\n`;
}
md += `\n`;
} else {
md += `Reliability failure modes evaluated against standard fault tolerance expectations.\n\n`;
}
// 10. Priority Recommendations
md += `## 10. Priority Recommendations (P0 Blocker, P1 Critical, P2 Improvement)\n\n`;
const p0 = findings.filter((f) => f.status === 'FAIL');
const p1 = findings.filter((f) => f.status === 'WARNING' && f.severity === 'high');
const p2 = findings.filter((f) => f.status === 'WARNING' && f.severity !== 'high');
let recIndex = 1;
if (p0.length > 0) {
md += `### P0 — Release Blockers\n`;
for (const item of p0) {
md += `${recIndex++}. **[P0 Blocker]** ${escapeMarkdown(item.title)}: ${escapeMarkdown(item.recommendation)}\n`;
}
md += `\n`;
}
if (p1.length > 0) {
md += `### P1 — High-Priority Operational Risks\n`;
for (const item of p1) {
md += `${recIndex++}. **[P1 Critical]** ${escapeMarkdown(item.title)}: ${escapeMarkdown(item.recommendation)}\n`;
}
md += `\n`;
}
if (p2.length > 0) {
md += `### P2 — Engineering Improvements & Hygiene\n`;
for (const item of p2) {
md += `${recIndex++}. **[P2 Improvement]** ${escapeMarkdown(item.title)}: ${escapeMarkdown(item.recommendation)}\n`;
}
md += `\n`;
}
if (p0.length === 0 && p1.length === 0 && p2.length === 0) {
md += `Zero blocking defects or open warnings identified. Architecture and code posture meet standard release criteria.\n\n`;
}
// 11. Evidence & Provenance
md += `## 11. Evidence & Provenance\n\n`;
md += `Every finding in this report is anchored to verifiable source code tokens, configuration files, or executed test commands:\n\n`;
const evidenceFindings = findings.filter((f) => f.evidence?.file || f.evidence?.command);
for (const ef of evidenceFindings.slice(0, 10)) {
const loc = ef.evidence.file || ef.evidence.command;
md += `- **[${ef.id}]**: Evidence captured from \`${escapeMarkdown(loc)}\` (provenance: \`${ef.provenance?.source || 'TOOL_MEASUREMENT'}\`)\n`;
}
md += `\n### Known Limitations\n`;
for (const lim of limitations) {
md += `- ${escapeMarkdown(lim)}\n`;
}
md += `\n`;
// 12. Formal Release Recommendation
const outcome = policyEvaluation?.outcome || 'UNKNOWN';
md += `## 12. Formal Release Recommendation\n\n`;
md += `### Release Gate Outcome: \`${outcome}\`\n\n`;
if (outcome === 'READY FOR HUMAN RELEASE REVIEW') {
md += `:white_check_mark: **READY FOR HUMAN RELEASE REVIEW**: All automated policy gates passed with zero blocking failures. Ready for release manager sign-off.\n\n`;
} else if (outcome === 'BLOCKED') {
md += `:x: **BLOCKED**: One or more critical or high severity defects must be resolved before release.\n\n`;
} else if (outcome === 'INCOMPLETE ASSESSMENT') {
md += `:warning: **INCOMPLETE ASSESSMENT**: Dynamic tests were skipped (read-only mode). Run with \`--allow-exec\` in an authorized environment to complete evaluation.\n\n`;
} else {
md += `:clipboard: **MANUAL REVIEW REQUIRED**: Heuristic items require engineering review prior to rollout.\n\n`;
}
if (policyEvaluation?.reasons?.length > 0) {
md += `**Evaluation Reasons**:\n`;
for (const reason of policyEvaluation.reasons) {
md += `- ${escapeMarkdown(reason)}\n`;
}
md += `\n`;
}
return md;
}
/**
* Formats 12 domain sections as a supplement for generateMarkdownReport.
*/
function format12DomainSections(report) {
let md = `\n## 9. Comprehensive 12-Domain Engineering Assessment\n\n`;
md += `This assessment covers the full 12-domain production engineering framework:\n\n`;
md += `1. **Project Overview & Topology**: Evaluated across repository inventory.\n`;
md += `2. **Architecture & System Design**: Evaluated across 17 mandatory design concepts.\n`;
md += `3. **Code Quality & Test Coverage**: Evaluated via static analysis and authorized execution.\n`;
md += `4. **Security Posture & Secrets Management**: Evaluated for environment boundaries and secret leakage.\n`;
md += `5. **Database Persistence & Migrations**: Evaluated for schema safety, connection pools, and indexing.\n`;
md += `6. **Frontend, UI & Accessibility**: Evaluated for WCAG AA compliance and public boundary leaks.\n`;
md += `7. **Mobile Engineering Readiness**: Evaluated for OWASP MASVS and platform security.\n`;
md += `8. **Performance & Capacity Modeling**: Evaluated with transparent capacity formulas and 10k-VU scenarios.\n`;
md += `9. **Reliability, Resilience & Failure Modes**: Evaluated with FMEA failure mode analysis.\n`;
md += `10. **Priority Recommendations**: Triaged into P0 (Blocker), P1 (Critical), P2 (Improvement).\n`;
md += `11. **Evidence & Provenance**: Grounded in empirical file and command evidence.\n`;
md += `12. **Formal Release Recommendation**: Explicit release gate verdict (\`${report.policyEvaluation?.outcome || 'UNKNOWN'}\`).\n\n`;
return md;
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |