@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/audit-dev-wire/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: audit-dev-wire
+description: Static parity gate between the generated frontend service URLs and the generated backend controller routes. Catches the "frontend calls a URL the backend never serves" class of bugs (the 404 the user sees in the browser) BEFORE runtime. Phase 3e gate of `/ba-develop`.
+group: D
+phase: devApi
+kind: audit
+audit_only: true
+section_label: 'AUDIT-DEV-WIRE (frontend service URL ↔ backend controller route parity)'
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# audit-dev-wire — Frontend ↔ Backend URL Parity Gate
+
+## Context
+
+You are running the static parity gate of `/ba-develop` Phase 3e. The CLI
+enumerates every URL the generated frontend services call AND every route
+the generated backend controllers expose, then diffs the two sets.
+
+A `wire.frontend-orphan` finding means the frontend will receive a 404 at
+runtime — exactly the failure the user reported with `GET /api/affaires/accueil/dashboard`.
+A `wire.backend-orphan` finding is informational — a route nobody calls
+(e.g. health probe, integration-stratum lookup) is not a defect.
+
+The audit reads:
+
+- `web/**/src/features/**/services/*Service.ts` — frontend service URLs
+- `web/**/src/features/**/hooks/use*.ts` — additional URL call sites
+- `src/<Ns>.Api/Controllers/**/*Controller.cs` — backend routes (both strata)
+
+It writes a structured JSON envelope on stdout (`auditReport.findings[]`)
+and a Markdown report under `_audit/dev-wire-<module>.md`.
+
+## When to run
+
+- **Automatically**: as Phase 3e of `/ba-develop`, after Phase 3 (Frontend)
+  has scaffolded all the api-clients and controllers. The orchestrator
+  calls the CLI; a single `err` finding blocks promotion to Phase 4.
+- **Manually**: when a developer suspects a 404 in their generated app,
+  run `audit-dev-wire --mode audit` to localise the drift in < 1 second.
+
+## Rules
+
+### DEV-WIRE-001 — Every frontend URL call has a backend route serving it
+
+- **Severity**: `err` (BLOCKING) on frontend orphans, `warn` on backend
+  orphans, `ok` when both sets align.
+- **Check**: cross-reference the canonicalised URL paths of every
+  `api.<verb>(<url>)` call in the frontend against every
+  `[Route]+[Http<Verb>]` declaration on the backend.
+- **fixSkill**: `backend-screen-controller` (when the orphan path matches
+  `/api/screens/...`) or `backend-controller` (when the orphan path matches
+  `/api/v1/integration/...`).
+- **fixPhaseKey**: `api`
+- **solution**: "Re-run the API phase. The orchestrator must re-invoke
+  `scaffold-screen-controller` (or `scaffold-controller`) for the entity
+  to emit the missing route. The frontend `*Service.ts` will then resolve
+  at runtime."
+
+### DEV-WIRE-002 — Verb mismatch on the same path
+
+- **Severity**: `err` (BLOCKING)
+- **Check**: when frontend and backend agree on the path but disagree on
+  the HTTP verb (frontend `POST`, backend `[HttpPut]`), surface the
+  discrepancy. The pagespec is the source of truth — the side that
+  diverges must be re-scaffolded.
+- **fixSkill**: `backend-screen-controller` if backend is wrong, otherwise
+  `frontend-api-client`.
+- **solution**: "Reconcile the pagespec.action.httpMethod with the controller
+  route attribute. Re-run the appropriate scaffolder; do not edit the
+  generated file by hand."
+
+### DEV-WIRE-003 — Strata mismatch
+
+- **Severity**: `err` (BLOCKING)
+- **Check**: frontend calls `/api/v1/integration/{plural}/...` (legacy
+  default) but only `{EntityPlural}ScreenController.cs` exists for that
+  entity — the screen-driven backend has no integration counterpart.
+- **fixSkill**: `frontend-api-client`
+- **fixPhaseKey**: `frontend`
+- **solution**: "Re-run `scaffold-api-client` for this entity with
+  `useScreens: true`. The Phase 3a strata detection (stat the screen
+  controller file) must have been out of order — verify the orchestrator's
+  step ordering."
+
+## Output contract
+
+The CLI emits a JSON envelope identical to `audit-dev-api`:
+
+```json
+{
+  "success": true,
+  "command": "audit-dev-wire",
+  "data": { "mode": "audit", "rulesRun": ["DEV-WIRE-001"], "valid": false },
+  "report": { /* full AuditReport with findings, counts, byRule, markdown */ },
+  "auditReport": {
+    "scope": "devWire",
+    "applicationCode": "gaf",
+    "moduleCode": "affaires",
+    "findings": [
+      {
+        "dimension": "devWire",
+        "code": "DEV-WIRE-001",
+        "severity": "err",
+        "label": "DEV_WIRE_001_err",
+        "params": { "calls": "GET /api/affaires/accueil/dashboard|src/features/affaires/demande/services/demandeService.ts" },
+        "solution": "Re-run the API phase ...",
+        "fixSkill": "backend-screen-controller",
+        "fixPhaseKey": "api"
+      }
+    ]
+  },
+  "errors": [],
+  "warnings": [],
+  "nextSteps": ["1 ERROR finding(s) — blocking Phase 3e gate of /ba-develop."]
+}
+```
+
+Exit code: `0` when no `err` findings, `1` otherwise.
+
+## CLI invocation
+
+```bash
+npx tsx skills/development/audit-dev-wire/cli/audit-dev-wire/index.ts \
+  --project-path "<dotnet-root>"     \
+  --web-path     "<web-root>"        \
+  --module-code  "<MODULE>"          \
+  --app-code     "<APP>"             \
+  --mode audit
+```
+
+`<web-root>` defaults to `<project-path>/web/<appCode>-web` if omitted.
+
+## Auto-healing mapping
+
+This audit emits failure kinds the `/ba-develop` orchestrator's auto-healing
+protocol picks up (see `ba-develop/references/auto-healing.md` rows 23-25):
+
+| Finding | Failure kind | Auto-fix |
+|---------|--------------|----------|
+| `DEV-WIRE-001 err` (path starts with `/api/screens/`) | `wire.frontend-orphan` (screen) | Re-invoke `scaffold-screen-controller` for the entity |
+| `DEV-WIRE-001 err` (path starts with `/api/v1/integration/`) | `wire.frontend-orphan` (integration) | Re-invoke `scaffold-controller` for the entity |
+| `DEV-WIRE-002 err` | `wire.verb-mismatch` | HALT for now — pagespec adjudication needed |
+| `DEV-WIRE-003 err` | `wire.strata-mismatch` | Re-invoke `scaffold-api-client` with `useScreens=true` |

package/templates/skills/development/audit-dev-wire/cli/audit-dev-wire/__tests__/audit.test.ts

@@ -0,0 +1,171 @@
+/**
+ * audit-dev-wire / audit.test.ts — Unit + fixture-driven tests of the parity
+ * audit. Verifies the 3 main cases the user originally hit:
+ *
+ *   1. Frontend calls /api/screens/demandes/list, backend has the matching
+ *      [HttpGet("list")] → no findings (the happy path the CLI now produces).
+ *   2. Frontend calls /api/affaires/accueil/dashboard (orphan URL from the
+ *      pre-Wave-1 apiBasePath template) → DEV-WIRE-001 err.
+ *   3. Backend has a route nobody calls → DEV-WIRE-001 warn (informational).
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { mkdir, writeFile, rm } from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { audit } from '../audit.js'
+
+let tmpRoot: string
+let webPath: string
+let backendPath: string
+
+beforeAll(async () => {
+  tmpRoot = await fsTempDir()
+  webPath = path.join(tmpRoot, 'web')
+  backendPath = path.join(tmpRoot, 'api')
+
+  // ─── Frontend service: hits /api/screens/demandes/list + bogus orphan ───
+  await mkdir(path.join(webPath, 'src/features/affaires/demande/services'), { recursive: true })
+  await writeFile(
+    path.join(webPath, 'src/features/affaires/demande/services/demandeService.ts'),
+    `import { api } from '@atlashub/smartstack';
+const API_PATH = '/api/screens/demandes';
+const INTEGRATION_PATH = '/api/v1/integration/demandes';
+
+export const demandeService = {
+  getAll: async () => {
+    const data = await api.get<unknown>(\`\${API_PATH}/list\`);
+    return data;
+  },
+  getOrphanDashboard: async () => {
+    // Pre-Wave-1 URL pattern that hits no backend route — the audit must flag this.
+    const data = await api.get<unknown>('/api/affaires/accueil/dashboard');
+    return data;
+  },
+  delete: async (id) => {
+    await api.delete(\`\${INTEGRATION_PATH}/\${id}\`);
+  },
+};
+`,
+    'utf8',
+  )
+
+  // ─── Backend controller: screen + integration strata ────────────────────
+  await mkdir(path.join(backendPath, 'src/Gaf.Api/Controllers/Affaires/Screens'), { recursive: true })
+  await writeFile(
+    path.join(backendPath, 'src/Gaf.Api/Controllers/Affaires/Screens/DemandesScreenController.cs'),
+    `using Microsoft.AspNetCore.Mvc;
+[ApiController]
+[Route("api/screens/demandes")]
+public class DemandesScreenController : ControllerBase
+{
+    [HttpGet("list")]
+    public IActionResult List() => Ok();
+}
+`,
+    'utf8',
+  )
+  await mkdir(path.join(backendPath, 'src/Gaf.Api/Controllers/Affaires'), { recursive: true })
+  await writeFile(
+    path.join(backendPath, 'src/Gaf.Api/Controllers/Affaires/DemandesController.cs'),
+    `using Microsoft.AspNetCore.Mvc;
+[ApiController]
+[Route("api/v1/integration/demandes")]
+public class DemandesController : ControllerBase
+{
+    [HttpDelete("{id:guid}")]
+    public IActionResult Delete(System.Guid id) => NoContent();
+
+    [HttpGet("lookup")]
+    public IActionResult Lookup() => Ok();
+}
+`,
+    'utf8',
+  )
+})
+
+afterAll(async () => {
+  if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true })
+})
+
+describe('audit-dev-wire / DEV-WIRE-001', () => {
+  it('flags the frontend orphan call as err (the user-visible 404)', async () => {
+    const report = await audit({
+      backendPath,
+      webPath,
+      moduleCode: 'affaires',
+      appCode: 'gaf',
+      mode: 'audit',
+      rules: [],
+    })
+
+    const orphans = report.findings.filter(
+      (f) => f.severity === 'err' && f.code === 'DEV-WIRE-001',
+    )
+    expect(orphans.length).toBeGreaterThanOrEqual(1)
+    const dashboard = orphans.find((f) =>
+      String(f.params.calls).includes('/api/affaires/accueil/dashboard'),
+    )
+    expect(dashboard).toBeDefined()
+    // The audit should classify this URL as "unknown stratum" — it sits
+    // outside both /api/v1/integration/* and /api/screens/*.
+    expect(dashboard!.params.stratum).toBe('unknown')
+    expect(dashboard!.fixSkill).toBeDefined()
+  })
+
+  it('does NOT flag matching list / delete / lookup pairs', async () => {
+    const report = await audit({
+      backendPath,
+      webPath,
+      moduleCode: 'affaires',
+      appCode: 'gaf',
+      mode: 'audit',
+      rules: [],
+    })
+
+    const orphans = report.findings.filter(
+      (f) => f.severity === 'err' && f.code === 'DEV-WIRE-001',
+    )
+    // The list call (GET /api/screens/demandes/list) has a matching backend
+    // route. The delete call (DELETE /api/v1/integration/demandes/{id}) also.
+    expect(orphans.find((f) => String(f.params.calls).includes('GET /api/screens/demandes/list'))).toBeUndefined()
+    expect(orphans.find((f) => String(f.params.calls).includes('DELETE /api/v1/integration/demandes'))).toBeUndefined()
+  })
+
+  it('skips lookup endpoints from the backend-orphan warn list', async () => {
+    const report = await audit({
+      backendPath,
+      webPath,
+      moduleCode: 'affaires',
+      appCode: 'gaf',
+      mode: 'audit',
+      rules: [],
+    })
+
+    // Backend has GET /api/v1/integration/demandes/lookup but no frontend
+    // caller in this fixture. Lookup is on the well-known no-caller allow-list.
+    const lookupWarn = report.findings.find(
+      (f) =>
+        f.severity === 'warn' &&
+        String(f.params.route).includes('/api/v1/integration/demandes/lookup'),
+    )
+    expect(lookupWarn).toBeUndefined()
+  })
+
+  it('produces a non-zero exit signal (counts.errors > 0) when a frontend orphan exists', async () => {
+    const report = await audit({
+      backendPath,
+      webPath,
+      moduleCode: 'affaires',
+      appCode: 'gaf',
+      mode: 'audit',
+      rules: [],
+    })
+    expect(report.counts.errors).toBeGreaterThan(0)
+  })
+})
+
+async function fsTempDir(): Promise<string> {
+  const dir = path.join(os.tmpdir(), `audit-dev-wire-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`)
+  await mkdir(dir, { recursive: true })
+  return dir
+}

package/templates/skills/development/audit-dev-wire/cli/audit-dev-wire/audit.ts

@@ -0,0 +1,307 @@
+/**
+ * audit-dev-wire / audit.ts — Static parity check between the generated
+ * frontend service URLs and the generated backend controller routes.
+ *
+ * MVP scope (Wave 2.1, 2026-05-27):
+ *   - DEV-WIRE-001: frontend-orphan (BLOCKING)   — primary 404 detector
+ *   - DEV-WIRE-001: backend-orphan  (INFO/warn)  — cleanup candidate
+ *
+ * Reserved (not yet implemented — captured in SKILL.md for forward compat):
+ *   - DEV-WIRE-002 verb-mismatch
+ *   - DEV-WIRE-003 strata-mismatch
+ *
+ * Frontend extraction is regex-driven (not a TS AST parser) — fast enough to
+ * scan a whole feature folder in milliseconds and resilient to small syntax
+ * shifts in the generated services (which are themselves regex-emitted by
+ * scaffold-api-client).
+ */
+import path from 'node:path'
+import { findFiles, readText } from '../../../../lib/fs.js'
+import { canonicaliseRoute } from '../../../../lib/url-conventions.js'
+import type {
+  AuditDevWireArgs,
+  AuditReport,
+  BackendRoute,
+  Finding,
+  FrontendCall,
+} from './types.js'
+
+// ─── Public entry ─────────────────────────────────────────────────────────
+
+export async function audit(args: AuditDevWireArgs): Promise<AuditReport> {
+  const frontendCalls = await loadFrontendCalls(path.resolve(args.webPath))
+  const backendRoutes = await loadBackendRoutes(path.resolve(args.backendPath))
+
+  const ruleFilter = new Set(args.rules)
+  const runAll = ruleFilter.size === 0
+  const findings: Finding[] = []
+
+  if (runAll || ruleFilter.has('DEV-WIRE-001')) {
+    findings.push(...checkDevWire001(frontendCalls, backendRoutes))
+  }
+
+  const counts = { errors: 0, warnings: 0, oks: 0 }
+  const byRule: Record<string, number> = {}
+  for (const f of findings) {
+    if (f.severity === 'err') counts.errors++
+    else if (f.severity === 'warn') counts.warnings++
+    else counts.oks++
+    byRule[f.code] = (byRule[f.code] ?? 0) + 1
+  }
+
+  const markdown = renderMarkdown({ counts, findings, args, frontendCalls, backendRoutes })
+
+  return {
+    scope: 'devWire',
+    applicationCode: args.appCode,
+    moduleCode: args.moduleCode,
+    backendPath: args.backendPath,
+    webPath: args.webPath,
+    filesInspected: frontendCalls.length + backendRoutes.length,
+    findings,
+    counts,
+    byRule,
+    markdown,
+  }
+}
+
+export function reportPath(backendPath: string, moduleCode: string): string {
+  return path.join(backendPath, '_audit', `dev-wire-${moduleCode}.md`)
+}
+
+// ─── DEV-WIRE-001 ──────────────────────────────────────────────────────────
+
+function checkDevWire001(
+  frontendCalls: FrontendCall[],
+  backendRoutes: BackendRoute[],
+): Finding[] {
+  const findings: Finding[] = []
+
+  // Index backend routes by normalised key.
+  const backendIndex = new Map<string, BackendRoute>()
+  for (const r of backendRoutes) {
+    backendIndex.set(routeKey(r.verb, r.urlPath), r)
+  }
+
+  // 1) frontend-orphan: every frontend call must find a backend route.
+  for (const call of frontendCalls) {
+    const key = routeKey(call.verb, call.urlPath)
+    if (backendIndex.has(key)) continue
+
+    const stratum = canonicaliseRoute(call.urlPath).stratum
+    const fixSkill =
+      stratum === 'screens' ? 'backend-screen-controller'
+      : stratum === 'integration' ? 'backend-controller'
+      : 'backend-screen-controller' // unknown stratum → re-scaffold likely missing screen controller
+    findings.push({
+      dimension: 'devWire',
+      code: 'DEV-WIRE-001',
+      severity: 'err',
+      label: 'DEV_WIRE_001_err',
+      params: {
+        calls: `${call.verb.toUpperCase()} ${call.urlPath}|${call.file}:${call.line}`,
+        stratum,
+      },
+      solution: stratum === 'unknown'
+        ? `Frontend calls \`${call.verb.toUpperCase()} ${call.urlPath}\` from ${call.file}:${call.line} but the URL doesn't match either canonical stratum (/api/v1/integration/* or /api/screens/*). Re-run scaffold-api-client for this entity — the URL was probably emitted by an obsolete \`apiBasePath\` template (removed on 2026-05-27).`
+        : `Frontend calls \`${call.verb.toUpperCase()} ${call.urlPath}\` from ${call.file}:${call.line} but no backend route matches. Re-invoke the appropriate scaffolder (${fixSkill}) for the entity to emit the missing route.`,
+      fixSkill,
+      fixPhaseKey: 'api',
+      file: call.file,
+    })
+  }
+
+  // 2) backend-orphan: every backend route should be called by ≥ 1 frontend
+  //    service. Informational only — lookup / health probes legitimately have
+  //    no frontend caller.
+  const frontendIndex = new Set<string>()
+  for (const c of frontendCalls) frontendIndex.add(routeKey(c.verb, c.urlPath))
+  for (const route of backendRoutes) {
+    const key = routeKey(route.verb, route.urlPath)
+    if (frontendIndex.has(key)) continue
+    // Skip well-known no-caller endpoints — they are legitimately backend-only.
+    if (/\/lookup$/.test(route.urlPath)) continue
+    if (/\/health/.test(route.urlPath)) continue
+    findings.push({
+      dimension: 'devWire',
+      code: 'DEV-WIRE-001',
+      severity: 'warn',
+      label: 'DEV_WIRE_001_warn',
+      params: {
+        route: `${route.verb.toUpperCase()} ${route.urlPath}|${route.file}`,
+        stratum: route.stratum,
+      },
+      solution: `Backend route \`${route.verb.toUpperCase()} ${route.urlPath}\` (${route.file}) has no frontend caller. Informational — confirm it's intended for machine-to-machine use or remove it.`,
+      file: route.file,
+    })
+  }
+
+  if (findings.length === 0) {
+    findings.push({
+      dimension: 'devWire',
+      code: 'DEV-WIRE-001',
+      severity: 'ok',
+      label: 'DEV_WIRE_001_ok',
+      params: { calls: frontendCalls.length, routes: backendRoutes.length },
+      solution: '',
+    })
+  }
+
+  return findings
+}
+
+function routeKey(verb: string, urlPath: string): string {
+  return `${verb.toLowerCase()} ${normalisePath(urlPath)}`
+}
+
+/** Collapse `{id:guid}` / `{id}` / `${var}` placeholders into a uniform `{p}`
+ *  so frontend and backend can match by structure rather than literal text. */
+function normalisePath(p: string): string {
+  return p
+    .replace(/\$\{[^}]+\}/g, '{p}')         // TS template substitutions
+    .replace(/\{[^:}]+:[^}]+\}/g, '{p}')    // ASP.NET typed segments `{id:guid}`
+    .replace(/\{[^}]+\}/g, '{p}')           // bare ASP.NET segments `{id}`
+    .replace(/\/+/g, '/')
+    .replace(/\/$/, '')
+}
+
+// ─── Frontend call loader ──────────────────────────────────────────────────
+
+const API_PATH_DECL_RE = /const\s+(API_PATH|INTEGRATION_PATH)\s*=\s*['"]([^'"]+)['"]/g
+const API_CALL_RE = /(?:^|\W)(?:api|client)\.(get|post|put|patch|delete)\s*<[^>]*>?\s*\(\s*(`[^`]+`|'[^']+'|"[^"]+"|[A-Z_]+)/g
+
+async function loadFrontendCalls(webPath: string): Promise<FrontendCall[]> {
+  const out: FrontendCall[] = []
+  // Generated services + hooks. Both can call the API.
+  const candidates = [
+    ...(await findFiles('**/services/*Service.ts', { cwd: webPath })),
+    ...(await findFiles('**/hooks/use*.ts', { cwd: webPath })),
+  ]
+  for (const abs of candidates) {
+    const source = await readText(abs)
+    if (!source) continue
+    const rel = path.relative(webPath, abs).replace(/\\/g, '/')
+
+    // 1) Capture the URL-base constants declared at the top of the file.
+    const baseLookup: Record<string, string> = {}
+    let bm: RegExpExecArray | null
+    API_PATH_DECL_RE.lastIndex = 0
+    while ((bm = API_PATH_DECL_RE.exec(source)) !== null) {
+      baseLookup[bm[1]] = bm[2]
+    }
+
+    // 2) Walk every api.<verb>(...) and pin its line number.
+    const lines = source.split(/\r?\n/)
+    let cursor = 0
+    for (let i = 0; i < lines.length; i++) {
+      const lineStart = cursor
+      const lineEnd = cursor + lines[i].length
+      cursor = lineEnd + 1
+      // Locate calls anchored on THIS line. We re-scan the whole `source`
+      // because some calls are wrapped across lines — the line of the verb
+      // itself is what matters for navigation.
+      const lineSource = lines[i]
+      let cm: RegExpExecArray | null
+      const lineRe = new RegExp(API_CALL_RE.source, 'g')
+      while ((cm = lineRe.exec(lineSource)) !== null) {
+        const verb = cm[1].toLowerCase()
+        const rawUrl = cm[2]
+        const urlPath = resolveUrl(rawUrl, baseLookup)
+        if (!urlPath) continue
+        // Skip absolute external URLs (not our concern).
+        if (!urlPath.startsWith('/api')) continue
+        out.push({ verb, urlPath, file: rel, line: i + 1 })
+      }
+      // Avoid unused-variable warning.
+      void lineStart
+    }
+  }
+  return out
+}
+
+function resolveUrl(raw: string, baseLookup: Record<string, string>): string | null {
+  // 1) Template literal: `${BASE}/suffix` or `${BASE}/${id}`
+  if (raw.startsWith('`')) {
+    const inner = raw.slice(1, -1)
+    // Replace ${BASE} with the captured base, leave other ${...} as placeholders.
+    return inner.replace(/\$\{([A-Z_]+)\}/g, (_match, name) => baseLookup[name] ?? `\${${name}}`)
+  }
+  // 2) Plain string literal.
+  if (raw.startsWith("'") || raw.startsWith('"')) {
+    return raw.slice(1, -1)
+  }
+  // 3) Bare identifier like `API_PATH` — substitute.
+  return baseLookup[raw] ?? null
+}
+
+// ─── Backend route loader (mirrors audit-dev-api/audit.ts pattern) ─────────
+
+const C_HTTP_VERBS = ['Get', 'Post', 'Put', 'Delete', 'Patch']
+const CLASS_ROUTE_RE = /\[Route\(\s*"([^"]+)"\s*\)\]/
+
+async function loadBackendRoutes(backendPath: string): Promise<BackendRoute[]> {
+  const out: BackendRoute[] = []
+  const files = await findFiles('**/*Controller.cs', { cwd: backendPath })
+  for (const abs of files) {
+    const source = await readText(abs)
+    if (!source) continue
+    const rel = path.relative(backendPath, abs).replace(/\\/g, '/')
+    const classRouteMatch = CLASS_ROUTE_RE.exec(source)
+    const classRouteRaw = classRouteMatch ? classRouteMatch[1] : ''
+    const classRoute = classRouteRaw.startsWith('/') ? classRouteRaw : `/${classRouteRaw}`
+    const stratumInfo = canonicaliseRoute(classRoute)
+    const methodRe = new RegExp(
+      `\\[Http(${C_HTTP_VERBS.join('|')})(?:\\(\\s*['"]([^'"]*)['"]\\s*\\))?\\s*\\]`,
+      'g',
+    )
+    let m: RegExpExecArray | null
+    while ((m = methodRe.exec(source)) !== null) {
+      const verb = m[1].toLowerCase()
+      const suffix = (m[2] ?? '').trim()
+      const urlPath = joinRoute(classRoute, suffix)
+      out.push({ verb, urlPath, file: rel, stratum: stratumInfo.stratum })
+    }
+  }
+  return out
+}
+
+function joinRoute(classRoute: string, suffix: string): string {
+  const base = classRoute.replace(/\/$/, '')
+  if (!suffix) return base
+  return `${base}/${suffix.replace(/^\//, '')}`
+}
+
+// ─── Markdown rendering ────────────────────────────────────────────────────
+
+function renderMarkdown(args: {
+  counts: { errors: number; warnings: number; oks: number }
+  findings: Finding[]
+  args: AuditDevWireArgs
+  frontendCalls: FrontendCall[]
+  backendRoutes: BackendRoute[]
+}): string {
+  const { counts, findings, args: a, frontendCalls, backendRoutes } = args
+  const lines: string[] = []
+  lines.push(`# audit-dev-wire — ${a.appCode}/${a.moduleCode}`)
+  lines.push('')
+  lines.push(`- Errors: **${counts.errors}**`)
+  lines.push(`- Warnings: ${counts.warnings}`)
+  lines.push(`- OKs: ${counts.oks}`)
+  lines.push(`- Frontend calls scanned: ${frontendCalls.length}`)
+  lines.push(`- Backend routes scanned: ${backendRoutes.length}`)
+  lines.push('')
+  if (findings.length === 0) {
+    lines.push('No findings.')
+    return lines.join('\n')
+  }
+  lines.push('| Code | Severity | Details |')
+  lines.push('|------|----------|---------|')
+  for (const f of findings) {
+    const details = Object.entries(f.params)
+      .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+      .join(' • ')
+    lines.push(`| ${f.code} | ${f.severity} | ${details} |`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}