@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/documentation/SKILL.md

@@ -1,139 +1,168 @@
----
-name: documentation
-description: |
-  Automatically generates technical documentation for SmartStack.
-  Use this skill when:
-  - User asks to create/generate documentation
-  - User mentions "document", "documentation", "doc", "ERD", "schema"
-  - User wants to document a module, table, tool, or test
-  - After implementing a feature to generate its documentation
-  Types: user module, developer tools, database ERD, testing tools
-argument-hint: "<module-name> [--type user|developer|database|testing|update]"
-model: sonnet
----
-
-<objective>
-Generate and maintain technical documentation integrated into SmartStack web app.
-Works in synergy with the `/documentation module` command.
-
-**Reference:** [_shared.md](../_shared.md) for architecture, i18n
-</objective>
-
-<quick_start>
-## WHEN THIS SKILL ACTIVATES
-
-### PREREQUISITE — ONLY post-implementation
-This skill requires the feature page to already exist (generated by /business-analyse-develop).
-It reads real TSX pages, controllers, and entities. Without them, nothing to document.
-
-→ For reviewing/editing the analysis BEFORE implementation: use ba-interactive.html (/business-analyse step-05)
-
-Claude automatically invokes this skill when it detects:
-
-| Trigger | Example |
-|---------|---------|
-| ❌ NEVER during BA | Before /business-analyse-develop — feature page does not exist yet |
-| Explicit request | "Document the SLA module" |
-| Documentation mention | "We should create the doc for..." |
-| After implementation | "The feature is done, generate the doc" |
-| Structure question | "How is the documentation organized?" |
-| Keywords | "ERD", "schema", "diagram", "document" |
-| **Update request** | "Update the doc", "refresh documentation", "doc is outdated" |
-| **Drift detected** | "The SLA documentation is stale" |
-</quick_start>
-
-<parameters>
-## DOCUMENTATION TYPES
-
-| Type | Description | Output |
-|------|-------------|--------|
-| `user` | User module (Mock UI) | `docs/business/{application}/{module}/index.tsx` (standalone TSX with Mock UI) |
-| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
-| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
-| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
-| `update` | Update existing documentation | Updates `doc-data.ts` + i18n FR |
-
-### Available Developer tools
-
-| Category | Tools |
-|----------|-------|
-| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
-| API Testing | Postman, REST Client, Swagger/OpenAPI |
-| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
-| Load Testing | NBomber (.NET), k6, Azure Load Testing |
-| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
-</parameters>
-
-<workflow>
-## WORKFLOW EXECUTION SEQUENCE
-
-The documentation skill executes in 4 progressive steps, each loaded on-demand:
-
-1. **[Step 00: Init](steps/step-00-init.md)** — Detect documentation type and gather context
-2. **[Step 01: Scan](steps/step-01-scan.md)** — Scan source code and extract data
-3. **[Step 02: Generate](steps/step-02-generate.md)** — Generate documentation content
-4. **[Step 03: Validate](steps/step-03-validate.md)** — Validate and integrate into SmartStack
-
-### Quick Reference
-
-| Type | Key Actions |
-|------|-----------|
-| `user` | Read real page TSX → Extract API/BR → Generate standalone annotated Mock UI TSX → Generate i18n (4 lang, FLAT) → Register routes/DocPanel |
-| `developer\|database\|testing` | Extract tool data → Generate doc-data.ts → Generate DocRenderer wrapper → Generate i18n (4 lang, nested) → Register routes |
-| `update` | Re-read real page TSX → Refresh API endpoints and business rules → Update i18n files (4 lang) → Update docs-manifest.json timestamps |
-
-</workflow>
-
-<entry_point>
-## SKILL ENTRY POINT
-
-**Start with:** [steps/step-00-init.md](steps/step-00-init.md)
-
-All execution flows through this progressive loading architecture. Each step file contains:
-- Clear execution sequence
-- Success metrics
-- Next step reference
-</entry_point>
-
-<execution_rules>
-## ABSOLUTE RULES
-
-1. **NEVER** hardcoded text → `useTranslation('namespace')`
-2. **NEVER** ASCII art → React/HTML components for ERD
-3. **ALWAYS** read the REAL page TSX before generating Mock UI
-4. **ALWAYS** read the controller to extract real API endpoints
-5. **ALWAYS** annotate every Mock UI section with `Annotation` components
-6. **ALWAYS** generate i18n in ALL 4 languages (FR, EN, DE, IT)
-7. **ALWAYS** use FLAT JSON (no root key) for standalone `user` type pages
-8. **ALWAYS** update App.tsx, docs-manifest.json, i18n/config.ts
-9. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
-10. **ALWAYS** update `DocPanelContext.tsx` mapping (IF type == `user`)
-11. **For `user` type:** Generate a standalone annotated Mock UI TSX page. **DO NOT use DocRenderer.**
-12. **For `developer|database|testing` types:** Use DocRenderer with `doc-data.ts` + `index.tsx` wrapper, pass `i18nNamespace` prop.
-13. **NEVER** include "Benefices" or "Avant/Apres" sections — this is documentation, not sales.
-</execution_rules>
-
-<step_files>
-## Step Files
-
-| Step | File | Purpose |
-|------|------|---------|
-| 00 | [steps/step-00-init.md](steps/step-00-init.md) | Detect documentation type and gather context |
-| 01 | [steps/step-01-scan.md](steps/step-01-scan.md) | Scan source code and extract data |
-| 02 | [steps/step-02-generate.md](steps/step-02-generate.md) | Generate documentation content |
-| 03 | [steps/step-03-validate.md](steps/step-03-validate.md) | Validate and integrate into SmartStack |
-</step_files>
-
-<success_criteria>
-- Documentation page renders correctly in React app
-- Mock UI faithfully reproduces the real page interface (not generic KPI/table)
-- Every Mock UI section has `Annotation` components explaining each visual element
-- i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct JSON format
-- Route registered in App.tsx
-- docs-manifest.json updated
-- i18n/config.ts updated with new namespace
-- Module appears in UserIndexPage (if type = user)
-- DocPanelContext.tsx mapping updated (if type = user)
-- BookOpen edge button opens correct doc for the module's routes
-- NO "Benefices" or "Avant/Apres" sections present
-</success_criteria>
+---
+name: documentation
+description: |
+  Automatically generates technical documentation for SmartStack.
+  Use this skill when:
+  - User asks to create/generate documentation
+  - User mentions "document", "documentation", "doc", "ERD", "schema"
+  - User wants to document a module, table, tool, or test
+  - After implementing a feature to generate its documentation
+  Types: user module, developer tools, database ERD, testing tools
+argument-hint: "<module-name> [--type user|developer|database|testing|update]"
+model: sonnet
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+<objective>
+Generate and maintain technical documentation integrated into the SmartStack web app.
+
+Two colocated CLIs do the deterministic work (`cli/extract-doc`, `cli/scaffold-doc`)
+and the ui-polish CLI enforces theme tokens; you author the faithful Mock UI in between.
+
+**Reference:** [_shared.md](../_shared.md) for architecture, i18n
+</objective>
+
+<quick_start>
+## WHEN THIS SKILL ACTIVATES
+
+### PREREQUISITE — ONLY post-implementation
+This skill requires the feature page to already exist (generated by /ba-develop).
+It reads real TSX pages, controllers, and entities. Without them, nothing to document.
+
+→ For reviewing/editing the analysis BEFORE implementation: use `/ba-audit-pre-dev`
+
+Claude automatically invokes this skill when it detects:
+
+| Trigger | Example |
+|---------|---------|
+| ❌ NEVER during BA | Before /ba-develop — feature page does not exist yet |
+| Explicit request | "Document the SLA module" |
+| Documentation mention | "We should create the doc for..." |
+| After implementation | "The feature is done, generate the doc" |
+| Structure question | "How is the documentation organized?" |
+| Keywords | "ERD", "schema", "diagram", "document" |
+| **Update request** | "Update the doc", "refresh documentation", "doc is outdated" |
+| **Drift detected** | "The SLA documentation is stale" |
+</quick_start>
+
+<parameters>
+## DOCUMENTATION TYPES
+
+| Type | Description | Output |
+|------|-------------|--------|
+| `user` | User module (Mock UI) | `docs/business/{group}/{application}/{module}/index.tsx` (standalone TSX with Mock UI) |
+| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
+| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
+| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
+| `update` | Update existing documentation | Re-run the CLIs (idempotent) |
+
+### Available Developer tools
+
+| Category | Tools |
+|----------|-------|
+| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
+| API Testing | Postman, REST Client, Swagger/OpenAPI |
+| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
+| Load Testing | NBomber (.NET), k6, Azure Load Testing |
+| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
+</parameters>
+
+<workflow>
+## WORKFLOW EXECUTION SEQUENCE
+
+Two colocated CLIs do the deterministic work; you author the faithful Mock UI in between.
+
+1. **[Step 00: Init](steps/step-00-init.md)** — Detect type + target + application
+2. **[Step 01: Scan](steps/step-01-scan.md)** — run **`extract-doc`** (real page, chart types, endpoints, rules, entity props)
+3. **[Step 02: Generate](steps/step-02-generate.md)** — author the page + i18n content, then run **`scaffold-doc`** (writes i18n + manifest, returns a wiring plan you apply)
+4. **[Step 03: Validate](steps/step-03-validate.md)** — run **ui-polish** (theme tokens) + verify wiring + typecheck
+
+### CLIs
+
+| CLI | Role |
+|-----|------|
+| `cli/extract-doc` | Read-only report: real page TSX, chart→Mock-UI mapping, API endpoints (resolved permissions), business rules, entity props, namespace/routes, **+ structure scan of the existing doc (`existingDoc.forbiddenSections` to strip, `existingDoc.missingRequired` = objective + header `summary` tagline to add)** |
+| `cli/scaffold-doc` | Writes 4 i18n files (FLAT for user / nested for DocRenderer) + upserts `docs-manifest.json` + emits the wiring plan (config.ts / DocRoutes.tsx / DocPanelContext.tsx / UserIndexPage.tsx) |
+| `development/frontend/ui-polish` | Enforces theme tokens (zero hardcoded colours) — replaces the old manual colour rules |
+
+> Invoke CLIs with `npx tsx skills/documentation/cli/<cli>/index.ts --spec '<JSON>'`.
+> On Windows PowerShell, call through the Bash tool (single-quoted JSON) or escape `"` as `\"`.
+
+### Quick Reference
+
+| Type | Key Actions |
+|------|-----------|
+| `user` | extract-doc → read real page → author standalone annotated Mock UI + FLAT i18n → scaffold-doc → apply wiring → ui-polish |
+| `developer\|database\|testing` | extract-doc (thin) + tool/schema data → author doc-data.ts + DocRenderer wrapper + FLAT i18n → scaffold-doc → apply wiring → ui-polish |
+| `update` | extract-doc (+ **strip any `existingDoc.forbiddenSections`, add any `existingDoc.missingRequired` = objective / header `summary`**) → refresh Mock UI / endpoints / rules → re-run scaffold-doc (idempotent) → ui-polish → §0 structure gate |
+</workflow>
+
+<entry_point>
+## SKILL ENTRY POINT
+
+**Start with:** [steps/step-00-init.md](steps/step-00-init.md)
+
+All execution flows through this progressive loading architecture. Each step file contains:
+- Clear execution sequence
+- Success metrics
+- Next step reference
+</entry_point>
+
+<execution_rules>
+## ABSOLUTE RULES
+
+1. **NEVER** hardcoded text → `useTranslation('<namespace>')`
+2. **NEVER** ASCII art → React/HTML components for ERD
+3. **ALWAYS** read the REAL page TSX (located by `extract-doc`) before writing Mock UI
+4. **ALWAYS** use the real endpoints / business rules from the `extract-doc` report (curated, not dumped verbatim)
+5. **ALWAYS** annotate every Mock UI section with the canonical `Annotation` component
+6. **ALWAYS** author i18n in ALL 4 languages (FR, EN, DE, IT)
+7. **i18n shape depends on type:** `user` = FLAT (no root key; resolved via `t('title')`); `developer/database/testing` = NESTED under the namespace key (resolved via `t('<namespace>.path')`). Author FLAT content — `scaffold-doc` wraps it for the DocRenderer types.
+8. **ALWAYS** run `scaffold-doc` (i18n files + manifest), then apply its wiring plan (config.ts, DocRoutes.tsx, DocPanelContext.tsx, UserIndexPage.tsx)
+9. **ALWAYS** run the ui-polish CLI before finishing (theme-token enforcement)
+10. **For `user` type:** standalone annotated Mock UI TSX page. **DO NOT use DocRenderer.**
+11. **For `developer|database|testing` types:** DocRenderer with `doc-data.ts` + `index.tsx` wrapper + `i18nNamespace` prop.
+12. **ALWAYS** lead with **Objectif** as Section 1 — a factual description of what the module does, as its own numbered section (never folded into the header subtitle). **NEVER** include problème/solution, "Bénéfices" or "Avant/Après" sections — this is documentation, not sales. Both sides are enforced by the step-03 §0 structure gate.
+
+### Theme / colour — delegated to the ui-polish CLI
+
+13. **Colour & token compliance is enforced by the ui-polish CLI**, not by hand. After the page exists, run it (step-03) in apply mode (`--regenerate-threshold 0`). Do NOT hand-map Tailwind colours or maintain a mapping table — the CLI maps hardcoded colours → theme tokens deterministically. See `development/frontend/ui-polish`.
+
+### Doc-specific intent the CLI can't infer (keep while authoring)
+
+14. **Dashboard chart series / KPI use the `--dataviz-*` palette** (`--dataviz-accent`, `--dataviz-cat-1..12`, `--dataviz-trend-*`) — never `--color-accent-*`/`--color-primary-*` for data series. Mirrors the real `DashboardPage.tsx`.
+15. **Brand colour = the themeable `--color-accent-*` ramp**, never the frozen `--color-primary-*` indigo.
+16. **Highlight blocks (Annotation, Tip, "Avec la fonctionnalité")** use the discreet accent pattern `border-l-2 border-[var(--color-accent-500)] bg-[var(--bg-secondary)]` — never `--info/success/warning/error-bg` (reserved for real alerts).
+
+### Mock UI fidelity + layout (user type — detail in templates.md)
+
+17. **Faithful reproduction**: match the real page's layout family + each chart's recharts type (`extract-doc` `charts[]`). Never a generic KPI/table substitute.
+18. **Expressive chart data**: ratio max/min(>0) ≥ 5x, visible peak + valley, height ≥ `h-24` (page) / `h-20` (DocPanel), real metric + unit (not abstract 0-100%).
+19. **Annotations** sit INSIDE the same padded container as the Mock UI they explain; compact (`px-3 py-2 text-xs`).
+20. **No DocPanel overflow**: `overflow-hidden` on chart cards, `min-w-0` on flex children, no fixed px bar widths; root container `space-y-8 max-w-5xl mx-auto pb-12` (no horizontal padding).
+21. **Official card pattern**: `p-N bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]` — not `className="card"`, not `rounded-lg`, not `bg-white`/`bg-gray-*`.
+22. **Fixed header block** (identical across pages): title + icon → **required accent tagline `t('summary')`** (`text-xl text-[var(--color-accent-600)] font-medium`) → `t('subtitle')` → inline stats line `<span>{N} {t('header.x')}</span>` (count as sibling text, **never** pills, **never** `t('header.x', {count})`). Missing tagline fails the §0 gate (`missingRequired` = `['summary']`).
+</execution_rules>
+
+<step_files>
+## Step Files
+
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | [steps/step-00-init.md](steps/step-00-init.md) | Detect documentation type, target, application |
+| 01 | [steps/step-01-scan.md](steps/step-01-scan.md) | Run `extract-doc` → report |
+| 02 | [steps/step-02-generate.md](steps/step-02-generate.md) | Author content, run `scaffold-doc`, apply wiring plan |
+| 03 | [steps/step-03-validate.md](steps/step-03-validate.md) | Run ui-polish, verify wiring, typecheck |
+</step_files>
+
+<success_criteria>
+- Documentation page renders correctly in the React app
+- Mock UI faithfully reproduces the real page interface (not generic KPI/table)
+- Every Mock UI section has `Annotation` components explaining each visual element
+- i18n files created in ALL 4 languages (FR, EN, DE, IT) — FLAT for `user`, nested under the namespace key for DocRenderer types
+- ui-polish reports 0 colour errors on the generated page
+- Wiring applied: route in `DocRoutes.tsx`, namespace in `i18n/config.ts`, `docs-manifest.json` entry, `DocPanelContext.tsx` mapping (+ `UserIndexPage.tsx` for user type)
+- Web app typechecks/builds
+- Header is the fixed block: title + **accent tagline `t('summary')`** + subtitle + inline stats line (counts as sibling text, not pills) — consistent across pages
+- Section 1 is **Objectif** (factual description of what the module does) AND no problème/solution, "Bénéfices" or "Avant/Après" framing — `extract-doc`'s `existingDoc.forbiddenSections` AND `existingDoc.missingRequired` (`objective`, `summary`) are all empty (step-03 §0 blocking gate)
+</success_criteria>

package/templates/skills/documentation/cli/extract-doc/__tests__/forbidden.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest'
+import { findForbidden } from '../extract.js'
+
+describe('extract-doc / findForbidden — i18n JSON', () => {
+  it('flags benefits / beforeAfter section-label keys', () => {
+    const json = `{
+  "sections": {
+    "objective": "Objectif",
+    "benefits": "Benefices concrets",
+    "beforeAfter": "Avant / Apres",
+    "faq": "Questions frequentes"
+  }
+}`
+    const hits = findForbidden(json, 'src/i18n/locales/fr/docs-support-sla.json')
+    expect(hits.map((h) => h.token).sort()).toEqual(['beforeAfter', 'benefits'])
+    // line numbers are 1-based and point at the offending key
+    expect(hits.every((h) => h.line > 0)).toBe(true)
+  })
+
+  it('flags overview.problem / overview.solution keys', () => {
+    const json = `{
+  "overview": {
+    "objective": "Gestion des SLA",
+    "problem": "Les engagements ne sont pas suivis",
+    "solution": "Monitoring automatique"
+  }
+}`
+    const hits = findForbidden(json, 'fr/docs-support-sla.json')
+    expect(hits.map((h) => h.token).sort()).toEqual(['problem', 'solution'])
+  })
+
+  it('does NOT flag a FAQ answer that merely contains the word "solution"', () => {
+    const json = `{
+  "faq": {
+    "1": {
+      "question": "Quel est le probleme resolu ?",
+      "answer": "La solution couvre le suivi automatique des SLA."
+    }
+  }
+}`
+    expect(findForbidden(json, 'fr/docs-support-sla.json')).toEqual([])
+  })
+
+  it('reports EVERY forbidden key on a single compact line', () => {
+    const json = `{ "overview": { "objective": "x", "problem": "p", "solution": "s" } }`
+    const hits = findForbidden(json, 'fr/docs-support-sla.json')
+    expect(hits.map((h) => h.token).sort()).toEqual(['problem', 'solution'])
+    expect(hits.every((h) => h.line === 1)).toBe(true)
+  })
+
+  it('returns nothing for a clean i18n file', () => {
+    const json = `{
+  "title": "SLA",
+  "objective": "Description factuelle",
+  "access": { "navigation": "Navigation" },
+  "features": { "1": { "title": "Config", "description": "..." } }
+}`
+    expect(findForbidden(json, 'fr/docs-support-sla.json')).toEqual([])
+  })
+})
+
+describe('extract-doc / findForbidden — doc-data.ts', () => {
+  it('flags benefits / beforeAfter object keys', () => {
+    const ts = `export const docData: DocData = {
+  overview: { objective: 'docsSupportSla.overview.objective' },
+  benefits: [
+    { icon: 'time', value: '-70%' },
+  ],
+  beforeAfter: {
+    beforeItems: ['Manual tracking'],
+    afterItems: ['Automated'],
+  },
+}`
+    const hits = findForbidden(ts, 'src/pages/docs/business/platform/support/sla/doc-data.ts')
+    expect(hits.map((h) => h.token).sort()).toEqual(['beforeAfter', 'benefits'])
+  })
+
+  it('flags overview.problem / overview.solution object keys', () => {
+    const ts = `export const docData: DocData = {
+  overview: {
+    objective: 'x',
+    problem: 'x',
+    solution: 'x',
+  },
+}`
+    const hits = findForbidden(ts, 'sla/doc-data.ts')
+    expect(hits.map((h) => h.token).sort()).toEqual(['problem', 'solution'])
+  })
+
+  it('returns nothing for a clean doc-data.ts', () => {
+    const ts = `export const docData: DocData = {
+  overview: { objective: 'x', stats: { useCases: 4 } },
+  useCases: [{ id: 'UC-001', name: 'Create' }],
+  features: [{ id: 'F-001', title: 'Config' }],
+}`
+    expect(findForbidden(ts, 'sla/doc-data.ts')).toEqual([])
+  })
+})
+
+describe('extract-doc / findForbidden — user TSX', () => {
+  it('flags a t() reference to a benefits/beforeAfter/problem/solution key', () => {
+    const tsx = `export default function SlaDocPage() {
+  const { t } = useTranslation('docsSupportSla')
+  return (
+    <section>
+      <h2>{t('sections.benefits')}</h2>
+      <p>{t('overview.solution')}</p>
+    </section>
+  )
+}`
+    const hits = findForbidden(tsx, 'src/pages/docs/business/platform/support/sla/index.tsx')
+    expect(hits.map((h) => h.token).sort()).toEqual(['benefits', 'solution'])
+  })
+
+  it('flags a hardcoded marketing section title (Avant / Après)', () => {
+    const tsx = `<h2 className="text-lg">Avant / Après</h2>`
+    const hits = findForbidden(tsx, 'sla/index.tsx')
+    expect(hits).toHaveLength(1)
+    expect(hits[0].token).toBe('literal-title')
+  })
+
+  it('does NOT flag a normal annotated Mock UI page', () => {
+    const tsx = `export default function SlaDocPage() {
+  const { t } = useTranslation('docsSupportSla')
+  return (
+    <div className="space-y-8 max-w-5xl mx-auto pb-12">
+      <h1>{t('title')}</h1>
+      <h2>{t('sections.objective')}</h2>
+      <p>{t('objective')}</p>
+      <Annotation>{t('interface.annotations.element1')}</Annotation>
+    </div>
+  )
+}`
+    expect(findForbidden(tsx, 'sla/index.tsx')).toEqual([])
+  })
+})

package/templates/skills/documentation/cli/extract-doc/__tests__/overflow.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest'
+import { findOverflowRisks } from '../extract.js'
+
+// Invariant under test: every `<code>` and every `font-mono` value in a `user`
+// doc page carries a break utility (`break-all` / `break-words` / `overflow-wrap`).
+// Without it a long unbreakable token (URL, permission key, namespace) fixes a
+// wide min-content on its grid/flex cell and overflows the card — the exact
+// PERMISSION / URL regression the gate now blocks.
+
+describe('extract-doc / findOverflowRisks — overflow-prone technical tokens', () => {
+  it('flags a <code> value with no break utility (the URL / permission card case)', () => {
+    const tsx = `<div className="min-w-0 p-3">
+  <code className="block text-xs text-[var(--text-secondary)]">{t('access.permission')}</code>
+</div>`
+    const hits = findOverflowRisks(tsx, 'src/pages/docs/business/platform/administration/themes/index.tsx')
+    expect(hits).toHaveLength(1)
+    expect(hits[0].token).toBe('code-no-break')
+    expect(hits[0].line).toBe(2) // 1-based, points at the offending element
+  })
+
+  it('flags a font-mono table cell with no break utility (API endpoints table)', () => {
+    const tsx = `<td className="py-2 px-3 font-mono text-xs">{ep.permission}</td>`
+    const hits = findOverflowRisks(tsx, 'themes/index.tsx')
+    expect(hits.map((h) => h.token)).toEqual(['mono-no-break'])
+  })
+
+  it('does NOT flag a <code> that already carries break-all', () => {
+    const tsx = `<code className="block text-xs break-all">{t('access.url')}</code>`
+    expect(findOverflowRisks(tsx, 'themes/index.tsx')).toEqual([])
+  })
+
+  it('does NOT flag a font-mono cell that carries break-all', () => {
+    const tsx = `<td className="py-2 px-3 font-mono text-xs break-all">{ep.path}</td>`
+    expect(findOverflowRisks(tsx, 'themes/index.tsx')).toEqual([])
+  })
+
+  it('accepts break-words / overflow-wrap as valid break utilities', () => {
+    const tsx = `<code className="break-words">{t('a')}</code>
+<span className="font-mono [overflow-wrap:anywhere]">{t('b')}</span>`
+    expect(findOverflowRisks(tsx, 'themes/index.tsx')).toEqual([])
+  })
+
+  it('does NOT flag a non-mono badge span (HTTP method badge)', () => {
+    const tsx = `<span className="px-2 py-0.5 rounded text-xs font-medium border">{ep.method}</span>`
+    expect(findOverflowRisks(tsx, 'themes/index.tsx')).toEqual([])
+  })
+
+  it('does NOT flag a plain annotated Mock UI line', () => {
+    const tsx = `<p className="text-[var(--text-secondary)] leading-relaxed">{t('objective')}</p>`
+    expect(findOverflowRisks(tsx, 'themes/index.tsx')).toEqual([])
+  })
+
+  it('reports a single finding for <code className="font-mono"> (code precedence, not double)', () => {
+    const tsx = `<code className="font-mono text-xs">{t('access.url')}</code>`
+    const hits = findOverflowRisks(tsx, 'themes/index.tsx')
+    expect(hits).toHaveLength(1)
+    expect(hits[0].token).toBe('code-no-break')
+  })
+
+  it('does not scan i18n JSON (only the page TSX carries layout)', () => {
+    const json = `{ "access": { "url": "/administration/uiconfiguration/themes" } }`
+    expect(findOverflowRisks(json, 'src/i18n/locales/fr/docs-administration-themes.json')).toEqual([])
+  })
+
+  it('returns nothing for a fully compliant access section', () => {
+    const tsx = `<div className="grid grid-cols-1 md:grid-cols-3 gap-3">
+  <div className="min-w-0 p-3 rounded-lg bg-[var(--bg-secondary)]">
+    <code className="block text-xs break-all">{t('access.url')}</code>
+  </div>
+  <div className="min-w-0 p-3 rounded-lg bg-[var(--bg-secondary)]">
+    <code className="block text-xs break-all">{t('access.permission')}</code>
+  </div>
+</div>`
+    expect(findOverflowRisks(tsx, 'themes/index.tsx')).toEqual([])
+  })
+})