Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.2.0
Last Updated: 2026-03-06
Status: Active Owning Core/Module: PF-75

​
Purpose

This standard defines how Encore Health OS enforces documentation comment quality and coverage for public TypeScript APIs. The goal is to improve maintainability and API clarity while enforcing durable standards for all in-scope exported APIs.

​
Scope

​
In Scope (initial)

  • src/platform/**
  • src/shared/**
  • src/cores/**
  • supabase/functions/**

​
Declaration types currently enforced for coverage

  • export function ...
  • export class ...
  • exported const initialized with function expressions / arrow functions

​
Initial exclusions

  • src/routes/** route/lazy-map files
  • src/integrations/** generated integration files
  • test/spec/story files
  • pure re-export barrels (export { ... } from ...)
  • type-heavy mapping files:
    • **/types.ts
    • **/types/**/*.ts
    • **/index.types.ts

​
TSDoc Syntax Rule

Default lint runs prioritize actionable runtime/code-quality findings.
TSDoc syntax debt is tracked via a dedicated command: 
npm run lint:debt:tsdoc
Coverage enforcement remains handled by the audit script, not by ESLint alone.

​
Coverage Audit Commands

# Full audit (includes minimum coverage checks)
npm run docs:comments:audit

# Changed-files gate (blocks undocumented new/changed exports)
npm run docs:comments:audit:changed

# Baseline report generation (non-blocking snapshot)
npm run docs:comments:baseline

# TSDoc syntax debt inventory (non-blocking)
npm run lint:debt:tsdoc

​
Output reports

  • reports/audits/TSDOC_JSDOC_COVERAGE_REPORT.md
  • reports/audits/TSDOC_JSDOC_COVERAGE_REPORT.json
  • reports/audits/TSDOC_JSDOC_COVERAGE_BASELINE.md
  • reports/audits/TSDOC_JSDOC_COVERAGE_BASELINE.json

​
Required Comment Quality

At minimum, public declarations should include:
  1. A concise summary line that describes behavior,
  2. @param tags for non-obvious parameters,
  3. @returns when return semantics are non-trivial,
  4. @deprecated with migration guidance and sunset where applicable.
Avoid filler comments that simply restate symbol names.

​
CI Policy

  1. Generate baseline report,
  2. Enforce no-regression on changed files (--fail-on-missing),
  3. Keep in-scope baseline coverage at 100%.

​
Threshold Policy

Minimum thresholds (for docs:comments:audit):
  • Global minimum: 100%
  • Area minimums:
    • platform: 100%
    • shared: 100%
    • cores: 100%
    • edge-functions: 100%
Any temporary exception must be documented in a tracked spec/errata item with owner and expiry.

​
Current Coverage Status

As of the latest baseline run:
  • Documented declarations: 8201 / 8201
  • Coverage: 100%

​
References

  • scripts/audit/audit-doc-comment-coverage.ts
  • specs/pf/specs/PF-75-tsdoc-jsdoc-coverage-program.md
  • AGENTS.md (current: see docs/VERSIONS.md)
  • constitution.md (current: see docs/VERSIONS.md)