Skip to content

v0.3.1 — orphan-readmes check + configurable thresholds + beacon about

Choose a tag to compare

View all tags
@Juliocbm Juliocbm released this 24 May 16:08
v0.3.1
5d15359

Patch release with three additions to the doctor + diagnostics surface.

✨ New doctor check: orphan-readmes (balance area)

Flags add-on category folders that were enabled with beacon enable <addon> but never received any actual content — only the auto-generated README still sits there 30+ days later.

◐ Balance (1)
  📁 docs/compliance/
    └─ orphan-readmes: Add-on enabled 47 days ago but folder still only contains README.md.
       → If you don't need this category, run `beacon disable compliance`.
         Otherwise add at least one doc (`beacon new <type> <slug>`).

Core categories (reference, architecture, adr, plans, backlog, evaluations) are intentionally exempt — they're expected to exist even when empty. Only add-on categories (compliance, business, modules, integrations, operations, roadmaps) get this nudge.

🎚️ Configurable doctor thresholds

Every threshold is now overridable per-project via doctor.thresholds in docs/_meta/beacon.config.json:

{
  "doctor": {
    "thresholds": {
      "stalePlanDays": 60,
      "proposedAdrDays": 21,
      "oldEvalMonths": 12,
      "orphanReadmeDays": 45,
      "backlogMinPlans": 10,
      "backlogPlansPerItem": 8
    }
  }
}

All fields optional. Unset → defaults. Invalid values (negative, NaN, non-number) silently ignored so a typo in the config never crashes the doctor. Zero migration — existing configs work unchanged. Rationale in ADR-010.

🩺 New command: beacon about

Diagnostics in one place — useful for bug reports and verifying installs:

$ beacon about
Beacon v0.3.1
  install path:  /usr/local/lib/node_modules/beacon-docs/dist/cli.js
  node version:  v20.10.0
  platform:      linux x64

Project config (docs/_meta/beacon.config.json)
  project type:  web-app
  categories:    reference, architecture, adr, plans, backlog, evaluations, business, integrations, operations, roadmaps (10)
  AI agents:     claude, cursor (2)
  language:      en
  thresholds:    2 overrides
    · stalePlanDays = 60 (default: 30)
    · proposedAdrDays = 21 (default: 14)

Generated AI files
  ✔ CLAUDE.md
  ✔ .cursorrules
  ✔ .cursor/rules/beacon.mdc

🧰 Internal

  • New module src/doctor/defaults.ts with resolveThresholds() — merges user config with defaults, validates types.
  • CheckContext extended with thresholds: Required<DoctorThresholds>; all 4 existing checks updated to read from it instead of module-level constants.
  • beacon about registered in CLI under a new "Diagnostics" help section + added to typo-correction and completion schemas.
  • Tests: +16 (255 → 271 passing across 44 files).

Install / upgrade

npm install -g beacon-docs@0.3.1
# verify install:
beacon about

Full changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md

Assets 2
Loading