mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
5e4ac5e472
- run-gates.ts docSyncLeafGates() gains verify-export-jsdoc — CI lanes and the pre-push hook execute this leaf list, not the doc-sync npm script, so the gate was previously unenforced there (proven by SessionForkErrorCode landing undocumented via a master merge while checks stayed green; now documented). Same wiring gap fixed for master's verify-config-catalog, which was also missing from the list. - The heritage exemption now recovers the base's return surface: a void base return carried no @returns duty, so an override returning a concrete result documents it itself (annotated overrides run the standard check; unannotated ones are classified by the checker so faithful void overrides need no boilerplate annotation). Three new negative-path tests pin it; RFC and module doc updated. - AGENTS.md states each principle inline instead of citing RFCs (eight citations removed; high-level doc links kept) and the editing section now carries the self-containedness rule. - Generated catalogs/graphs regenerated for the shifted line pointers.
644 lines
34 KiB
TypeScript
644 lines
34 KiB
TypeScript
/**
|
|
* Verify JSDoc completeness for EVERY module-level exported name of every
|
|
* non-vendored package (each `packages/<group>/<pkg>/src/` tree). This is the
|
|
* mechanical form of the AGENTS.md rule "every export has a JSDoc explaining
|
|
* semantics", generalizing the cordis-surface gate (`gen-cordis-catalog.ts`,
|
|
* which owns `interface Events` members and `ctx.<key>` service classes) to
|
|
* the whole export surface; the parsing + check helpers are shared via
|
|
* `scripts/jsdoc.ts` so "documented" means the same thing on both.
|
|
*
|
|
* `tsx scripts/verify-export-jsdoc.ts` → exit 1 listing every offender
|
|
*
|
|
* The contract, per exported declaration kind:
|
|
*
|
|
* - Every exported name needs JSDoc with non-empty description prose (prose
|
|
* ends at the first block tag, standard JSDoc semantics).
|
|
* - A function-like export (function declaration, a const with a function
|
|
* initializer or an INLINE callable annotation, or a non-identifier
|
|
* function default export) additionally needs a non-empty `@param` per
|
|
* parameter (`this` receiver annotations exempt; a stale `@param` errors)
|
|
* and a non-empty `@returns` unless the return type is `void` /
|
|
* `Promise<void>`. Wrapper expressions (parentheses, `as` / `satisfies`
|
|
* casts, non-null assertions) are peeled before classifying. The walk
|
|
* classifies returns syntactically, so the return type must be ANNOTATED —
|
|
* except a const whose declarator is annotated with a NAMED type (e.g.
|
|
* `export const f: Handler = …`), where that type's own declaration owns
|
|
* the signature contract and `@returns` stays optional; an inline
|
|
* `(x: T) => U` annotation or single-call-signature literal is the surface
|
|
* signature itself and gets the full contract, and a literal mixing
|
|
* call/construct signatures with anything else is refused (extract a named
|
|
* type).
|
|
* - An exported class needs class-level JSDoc; its public methods (static
|
|
* included — they are reachable on the exported name) follow the function
|
|
* contract, and public properties and accessors need description prose (on
|
|
* a get/set pair the getter's doc covers both). A member declared by an
|
|
* `extends`/`implements` heritage type is EXEMPT — the seam declaration is
|
|
* the doc's one home, the IDE inherits it, and re-documenting every
|
|
* implementation invites drift — UNLESS the override grows surface the
|
|
* base never documented: a protected-only base member does not exempt a
|
|
* public override, parameters the base never names keep their `@param`
|
|
* duty, and a concrete result above a void base return keeps its
|
|
* `@returns` duty. Heritage members (and classifying an unannotated
|
|
* override's inferred return above a void base) are the questions the walk
|
|
* asks the TYPE CHECKER; everything else is pure AST.
|
|
* Constructors are exempt like the cordis gate's: plugin classes are
|
|
* framework-constructed, and the class doc owns the story.
|
|
* - Exported interfaces, type aliases, enums: description prose on the
|
|
* declaration (member-level docs stay review's job; the highest-value
|
|
* member surface — seam service classes — is already under the cordis
|
|
* gate).
|
|
* - An exported namespace recurses (its exported members are package
|
|
* surface; in an ambient `declare` namespace every member exports
|
|
* implicitly); the namespace itself needs prose only when it does not
|
|
* merge with an already-documented same-name declaration (the
|
|
* Config-namespace idiom documents the class/function once, not twice).
|
|
* - The cordis plugin-protocol slots are exempt: top-level `name` / `inject`
|
|
* / `reusable` / `Config` consts and the `apply` entry, plus the same
|
|
* slots as statics on a plugin class. Their shape is fixed by the
|
|
* framework, so a doc would restate the protocol — the module doc comment
|
|
* and the `interface Config` carry the plugin's real semantics. (These
|
|
* names are reserved by cordis convention; documenting one anyway is
|
|
* allowed, only absence goes unchecked.)
|
|
* - Overload groups: each overload signature carries its own docs; the
|
|
* implementation signature is exempt (callers never see it).
|
|
* - Skipped: `declare module` / `declare global` augmentation bodies (the
|
|
* cordis gate's turf; an augmentation is not an export of the package) and
|
|
* re-export statements with a module specifier (`export … from`) — the
|
|
* defining module is walked on its own, and external definitions are not
|
|
* ours to document. An `export import X = N.member` alias documents
|
|
* ITSELF, and only prose-only target kinds are gate-supported: a callable,
|
|
* class, or namespace target carries signature/member contracts the alias
|
|
* cannot hold and is refused (export the declaration directly).
|
|
* - Everything else fails CLOSED: `export =` is refused outright, and an
|
|
* exported statement kind the dispatch does not recognize is itself a
|
|
* violation, so no export form can pass unchecked by omission.
|
|
*/
|
|
|
|
import { existsSync, globSync } from 'node:fs'
|
|
import { resolve } from 'node:path'
|
|
import ts from 'typescript'
|
|
import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc } from './jsdoc.ts'
|
|
|
|
const root = resolve(import.meta.dirname, '..')
|
|
|
|
/** Plugin-protocol slot names exempt as statics on an exported class. */
|
|
const PROTOCOL_STATICS = new Set(['Config', 'inject', 'name', 'reusable'])
|
|
|
|
/** Plugin-protocol slot names exempt as top-level exports (const or function). */
|
|
const PROTOCOL_EXPORTS = new Set(['Config', 'inject', 'name', 'reusable', 'apply'])
|
|
|
|
/** Per-file walk state threaded through the scope recursion. */
|
|
interface Walk {
|
|
/** Repo-relative path of the file being walked. */
|
|
rel: string
|
|
/** The parsed source file. */
|
|
sf: ts.SourceFile
|
|
/** Raw file text (rawJsDoc reads comment ranges out of it). */
|
|
text: string
|
|
/** The program's checker, consulted only for heritage-member lookups. */
|
|
checker: ts.TypeChecker
|
|
/** The aggregate violation list, appended in place. */
|
|
violations: string[]
|
|
}
|
|
|
|
/** True when a statement carries the `export` modifier. */
|
|
function isExported(stmt: ts.Statement): boolean {
|
|
return ts.canHaveModifiers(stmt) && (ts.getModifiers(stmt)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)
|
|
}
|
|
|
|
/** True for a class member a consumer cannot reach: `private`/`protected`/`#name`. */
|
|
function isNonPublic(member: ts.ClassElement): boolean {
|
|
const mods = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
|
|
return (mods?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false)
|
|
|| ('name' in member && ts.isPrivateIdentifier(member.name))
|
|
}
|
|
|
|
/** True when a class member carries the `static` modifier. */
|
|
function isStatic(member: ts.ClassElement): boolean {
|
|
const mods = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
|
|
return mods?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) ?? false
|
|
}
|
|
|
|
/** The `this`-receiver exemption every function-like check shares. */
|
|
function thisReceiver(p: ts.ParameterDeclaration): boolean {
|
|
return ts.isIdentifier(p.name) && p.name.text === 'this'
|
|
}
|
|
|
|
/**
|
|
* Peel wrapper expressions that carry no surface of their own — parentheses,
|
|
* `as` / `satisfies` / angle-bracket casts, non-null assertions — so a
|
|
* wrapped function expression is still classified as function-like.
|
|
* @param e - the expression to unwrap.
|
|
* @returns the innermost non-wrapper expression.
|
|
*/
|
|
function unwrapExpression(e: ts.Expression): ts.Expression {
|
|
let inner = e
|
|
while (
|
|
ts.isParenthesizedExpression(inner) || ts.isAsExpression(inner) || ts.isSatisfiesExpression(inner)
|
|
|| ts.isNonNullExpression(inner) || ts.isTypeAssertionExpression(inner)
|
|
) inner = inner.expression
|
|
return inner
|
|
}
|
|
|
|
/**
|
|
* Classify a declarator's type annotation for the function contract: an
|
|
* inline function type or a type literal that is EXACTLY one call signature
|
|
* is the surface signature itself; a literal mixing call/construct
|
|
* signatures with anything else cannot be classified syntactically and is
|
|
* refused (fail closed — extract a named type); everything else is a plain
|
|
* value shape.
|
|
* @param type - the declarator's type annotation.
|
|
* @returns the signature to check, 'refuse' for an unclassifiable callable literal, or null for a non-callable shape.
|
|
*/
|
|
function callableAnnotation(type: ts.TypeNode): ts.SignatureDeclarationBase | 'refuse' | null {
|
|
if (ts.isFunctionTypeNode(type)) return type
|
|
if (!ts.isTypeLiteralNode(type)) return null
|
|
const signatures = type.members.filter(m => ts.isCallSignatureDeclaration(m) || ts.isConstructSignatureDeclaration(m))
|
|
if (signatures.length === 0) return null
|
|
if (signatures.length === 1 && type.members.length === 1 && signatures[0] !== undefined && ts.isCallSignatureDeclaration(signatures[0])) {
|
|
return signatures[0]
|
|
}
|
|
return 'refuse'
|
|
}
|
|
|
|
/**
|
|
* The heritage-member exemption for one class member. When the member's name
|
|
* is declared by an `extends`/`implements` heritage type, the seam declaration
|
|
* is the doc's one home (the IDE inherits it on hover) and the member needs no
|
|
* doc of its own — EXCEPT where the override grows public surface the base
|
|
* never documented: a base member that is protected on every declaration does
|
|
* not exempt a public override (consumers could not call it before);
|
|
* parameters the base never names keep their own `@param` duty (the caller
|
|
* reads the seam doc, which cannot describe them; an underscore-prefixed
|
|
* rename of a base parameter — the deliberately-unused marker — is the same
|
|
* parameter, not new surface); and a void base return carried no `@returns`
|
|
* duty, so an override returning a concrete result documents it itself.
|
|
* Static members are looked up on the base CONSTRUCTOR type (only an
|
|
* `extends` expression has one; an unresolvable or interface expression
|
|
* yields no property and therefore no exemption).
|
|
* @param cls - the class whose heritage to search.
|
|
* @param name - the member name to look up.
|
|
* @param staticSide - whether to search the constructor side instead of the instance side.
|
|
* @param checker - the program's type checker.
|
|
* @returns null when no exemption applies; otherwise the parameter names the
|
|
* base declarations carry (`baseParams: null` when not syntactically
|
|
* recoverable — a complex heritage type — exempting all parameters) plus
|
|
* whether every recoverable base return annotation is `void`-like
|
|
* (`baseVoidReturn: null` when none is recoverable, exempting the result).
|
|
*/
|
|
function heritageExemption(
|
|
cls: ts.ClassDeclaration,
|
|
name: string,
|
|
staticSide: boolean,
|
|
checker: ts.TypeChecker,
|
|
): { baseParams: Set<string> | null; baseVoidReturn: boolean | null } | null {
|
|
const isProtected = (d: ts.Declaration): boolean =>
|
|
(ts.canHaveModifiers(d) ? ts.getModifiers(d) : undefined)?.some(m => m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false
|
|
for (const clause of cls.heritageClauses ?? []) {
|
|
for (const t of clause.types) {
|
|
const type = staticSide ? checker.getTypeAtLocation(t.expression) : checker.getTypeAtLocation(t)
|
|
const prop = type.getProperty(name)
|
|
if (prop === undefined) continue
|
|
const decls = prop.declarations ?? []
|
|
if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new surface
|
|
let baseParams: Set<string> | null = null
|
|
let baseVoidReturn: boolean | null = null
|
|
for (const d of decls) {
|
|
let params: readonly ts.ParameterDeclaration[] | undefined
|
|
let returnType: ts.TypeNode | undefined
|
|
if (ts.isMethodDeclaration(d) || ts.isMethodSignature(d)) {
|
|
params = d.parameters
|
|
returnType = d.type
|
|
} else if ((ts.isPropertySignature(d) || ts.isPropertyDeclaration(d)) && d.type !== undefined && ts.isFunctionTypeNode(d.type)) {
|
|
params = d.type.parameters
|
|
returnType = d.type.type
|
|
} else continue
|
|
baseParams ??= new Set()
|
|
// Leading underscores are the deliberately-unused marker (eslint
|
|
// argsIgnorePattern), not a rename: `_cwd` overriding `cwd` is the
|
|
// same parameter, so compare underscore-stripped on both sides.
|
|
for (const p of params) if (ts.isIdentifier(p.name)) baseParams.add(p.name.text.replace(/^_+/, ''))
|
|
if (returnType !== undefined) {
|
|
const voidish = /^(void|Promise<void>)$/.test(returnType.getText(d.getSourceFile()).replace(/\s+/g, ' '))
|
|
baseVoidReturn = (baseVoidReturn ?? true) && voidish
|
|
}
|
|
}
|
|
return { baseParams, baseVoidReturn }
|
|
}
|
|
}
|
|
return null
|
|
}
|
|
|
|
/**
|
|
* True when a method's INFERRED return type is void-like (void, undefined,
|
|
* never, or a promise of one) — the one return the walk asks the checker to
|
|
* classify: an unannotated override above a void heritage member, where
|
|
* demanding an annotation just to prove faithfulness would be boilerplate.
|
|
* @param m - a method declaration with no return type annotation.
|
|
* @param checker - the program's type checker.
|
|
* @returns true when the inferred result carries nothing to document.
|
|
*/
|
|
function inferredReturnIsVoidish(m: ts.MethodDeclaration, checker: ts.TypeChecker): boolean {
|
|
const sig = checker.getSignatureFromDeclaration(m)
|
|
if (sig === undefined) return true // no callable signature: nothing classifiable to document
|
|
const returned = checker.getReturnTypeOfSignature(sig)
|
|
const awaited = checker.getAwaitedType(returned) ?? returned
|
|
return (awaited.flags & (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never)) !== 0
|
|
}
|
|
|
|
/**
|
|
* Check description-prose presence for one labeled declaration: JSDoc must
|
|
* exist and carry prose above its block tags.
|
|
* @param where - the offender label violations open with.
|
|
* @param raw - the declaration's raw JSDoc block ('' if none).
|
|
* @param w - the walk state violations append to.
|
|
*/
|
|
function checkDescribed(where: string, raw: string, w: Walk): void {
|
|
if (!raw) w.violations.push(`${where} has no JSDoc.`)
|
|
else if (!parseJsDoc(raw).doc) w.violations.push(`${where} has no description prose above its block tags.`)
|
|
}
|
|
|
|
/**
|
|
* Check the full function contract for one labeled function-like declaration:
|
|
* description prose, `@param` per parameter, `@returns` on a non-void result.
|
|
* @param where - the offender label violations open with.
|
|
* @param raw - the declaration's raw JSDoc block ('' if none).
|
|
* @param parameters - the declaration's parameter list.
|
|
* @param returnType - the return type annotation, or undefined when inferred.
|
|
* @param returnsWaived - suppress the `@returns`/annotation requirement (a
|
|
* declarator-annotated const defers its return contract to the named type).
|
|
* @param w - the walk state violations append to.
|
|
*/
|
|
function checkFunctionLike(
|
|
where: string,
|
|
raw: string,
|
|
parameters: readonly ts.ParameterDeclaration[],
|
|
returnType: ts.TypeNode | undefined,
|
|
returnsWaived: boolean,
|
|
w: Walk,
|
|
): void {
|
|
if (!raw) { w.violations.push(`${where} has no JSDoc.`); return }
|
|
if (!parseJsDoc(raw).doc) w.violations.push(`${where} has no description prose above its block tags.`)
|
|
const { params, returns } = parseTags(raw)
|
|
checkParams(where, 'export', parameters, params, w.sf, thisReceiver, w.violations)
|
|
if (!returnsWaived) checkReturns(where, returnType, returns, w.sf, w.violations)
|
|
}
|
|
|
|
/**
|
|
* Check one exported class: class-level prose, the function contract on every
|
|
* public method (overload implementations exempt), and description prose on
|
|
* public properties and accessors (a get/set pair is covered by the getter's
|
|
* doc). Heritage-declared members are exempt per heritageExemption (an
|
|
* override's extra parameters keep their @param duty); plugin-protocol
|
|
* statics are exempt; constructors are not checked (framework-constructed
|
|
* plugins, and the class doc owns the story).
|
|
* @param cls - the exported class declaration.
|
|
* @param name - the class's surface name (namespace-qualified).
|
|
* @param w - the walk state violations append to.
|
|
*/
|
|
function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
|
|
checkDescribed(`exported class '${name}' (${pointer(w.rel, w.sf, cls)})`, rawJsDoc(w.text, cls), w)
|
|
const overloadSigs = new Set<string>()
|
|
const documentedGetters = new Set<string>()
|
|
for (const m of cls.members) {
|
|
if ('name' in m && ts.isComputedPropertyName(m.name)) continue
|
|
if (ts.isMethodDeclaration(m) && !m.body) overloadSigs.add(m.name.getText(w.sf))
|
|
if (ts.isGetAccessorDeclaration(m)) documentedGetters.add(m.name.getText(w.sf))
|
|
}
|
|
for (const m of cls.members) {
|
|
if (isNonPublic(m) || ts.isConstructorDeclaration(m)) continue
|
|
if (!('name' in m) || ts.isComputedPropertyName(m.name)) continue // computed/symbol members
|
|
const mname = m.name.getText(w.sf)
|
|
if (isStatic(m) && PROTOCOL_STATICS.has(mname)) continue // cordis plugin-protocol slot
|
|
const exemption = heritageExemption(cls, mname, isStatic(m), w.checker)
|
|
if (ts.isMethodDeclaration(m)) {
|
|
if (m.body && overloadSigs.has(mname)) continue // overload implementation: the signatures carry the docs
|
|
const where = `exported class method '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`
|
|
if (exemption !== null) {
|
|
const raw = rawJsDoc(w.text, m)
|
|
// The heritage declaration owns the prose; parameters the base never
|
|
// names — including binding patterns, which no base declaration can
|
|
// name — are new surface and keep their @param duty.
|
|
const base = exemption.baseParams
|
|
const inBase = (p: ts.ParameterDeclaration): boolean =>
|
|
base !== null && ts.isIdentifier(p.name) && base.has(p.name.text.replace(/^_+/, ''))
|
|
if (base !== null && m.parameters.some(p => !thisReceiver(p) && !inBase(p))) {
|
|
checkParams(where, 'export', m.parameters, parseTags(raw).params, w.sf,
|
|
p => thisReceiver(p) || inBase(p), w.violations)
|
|
}
|
|
// A void base return carried no @returns duty, so an override growing
|
|
// a concrete result documents it itself. An annotated override runs
|
|
// the standard check; an inferred one is classified by the checker
|
|
// (this branch is already the checker's domain), so a faithful void
|
|
// override stays exempt without a boilerplate annotation.
|
|
if (exemption.baseVoidReturn === true) {
|
|
if (m.type !== undefined) {
|
|
checkReturns(where, m.type, parseTags(raw).returns, w.sf, w.violations)
|
|
} else if (!inferredReturnIsVoidish(m, w.checker)) {
|
|
w.violations.push(`${where} returns a non-void result its heritage declaration does not document; annotate the return type and add @returns.`)
|
|
}
|
|
}
|
|
continue
|
|
}
|
|
checkFunctionLike(where, rawJsDoc(w.text, m), m.parameters, m.type, false, w)
|
|
} else if (exemption !== null) {
|
|
continue // the heritage declaration owns the doc (properties/accessors carry no own parameters)
|
|
} else if (ts.isGetAccessorDeclaration(m) || ts.isPropertyDeclaration(m)) {
|
|
const kind = ts.isPropertyDeclaration(m) ? 'property' : 'accessor'
|
|
checkDescribed(`exported class ${kind} '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
|
|
} else if (ts.isSetAccessorDeclaration(m) && !documentedGetters.has(mname)) {
|
|
checkDescribed(`exported class accessor '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
|
|
}
|
|
// index signatures / static blocks: not named surface
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Check one exported declaration statement, dispatching on its kind. Any
|
|
* exported statement kind the dispatch does not recognize is a violation
|
|
* (fail closed), so no export form can pass unchecked by omission.
|
|
* @param stmt - the exported statement (export modifier or export-list target).
|
|
* @param prefix - the namespace qualification for surface names ('' at top level).
|
|
* @param overloadSigs - names in this scope declared as bodyless function overload signatures.
|
|
* @param byName - this scope's named declarations (for namespace/sibling-merge lookups).
|
|
* @param ambient - whether the enclosing scope is ambient (`declare`), where members export implicitly.
|
|
* @param w - the walk state violations append to.
|
|
* @param only - for a multi-declarator variable statement reached through an
|
|
* export list (or a default-export identifier), the declarator names that
|
|
* are actually exported; `null` means the whole statement is surface
|
|
* (direct `export` modifier or ambient scope). Non-variable statements
|
|
* declare exactly one name, so the filter never applies to them.
|
|
*/
|
|
function checkDecl(
|
|
stmt: ts.Statement,
|
|
prefix: string,
|
|
overloadSigs: Set<string>,
|
|
byName: Map<string, ts.Statement[]>,
|
|
ambient: boolean,
|
|
w: Walk,
|
|
only: ReadonlySet<string> | null = null,
|
|
): void {
|
|
const at = (n: ts.Node): string => ` (${pointer(w.rel, w.sf, n)})`
|
|
if (ts.isFunctionDeclaration(stmt)) {
|
|
const name = stmt.name?.text ?? 'default'
|
|
if (prefix === '' && PROTOCOL_EXPORTS.has(name)) return // cordis plugin-protocol slot
|
|
if (stmt.body && overloadSigs.has(name)) return // overload implementation: the signatures carry the docs
|
|
checkFunctionLike(`exported function '${prefix}${name}'${at(stmt)}`, rawJsDoc(w.text, stmt),
|
|
stmt.parameters, stmt.type, false, w)
|
|
return
|
|
}
|
|
if (ts.isClassDeclaration(stmt)) {
|
|
checkClass(stmt, `${prefix}${stmt.name?.text ?? 'default'}`, w)
|
|
return
|
|
}
|
|
if (ts.isInterfaceDeclaration(stmt)) {
|
|
checkDescribed(`exported interface '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
|
|
return
|
|
}
|
|
if (ts.isTypeAliasDeclaration(stmt)) {
|
|
checkDescribed(`exported type '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
|
|
return
|
|
}
|
|
if (ts.isEnumDeclaration(stmt)) {
|
|
checkDescribed(`exported enum '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
|
|
return
|
|
}
|
|
if (ts.isVariableStatement(stmt)) {
|
|
const raw = rawJsDoc(w.text, stmt) // JSDoc sits on the statement, not the declarator
|
|
for (const d of stmt.declarationList.declarations) {
|
|
const name = ts.isIdentifier(d.name) ? d.name.text : d.name.getText(w.sf)
|
|
if (only !== null && !only.has(name)) continue // sibling declarator the export list never named: not surface
|
|
if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
|
|
const where = `exported const '${prefix}${name}'${at(d)}`
|
|
const annotation = d.type !== undefined ? callableAnnotation(d.type) : null
|
|
const init = d.initializer !== undefined ? unwrapExpression(d.initializer) : undefined
|
|
if (annotation === 'refuse') {
|
|
// A literal mixing call/construct signatures with other members (or
|
|
// overloading them) has no single signature the walk can hold the
|
|
// tags against — fail closed rather than silently narrow the check.
|
|
w.violations.push(`${where}: its callable type literal is not gate-classifiable; extract a named type and document it there.`)
|
|
} else if (annotation !== null) {
|
|
// An INLINE callable annotation is the surface signature itself: its
|
|
// parameters and result need docs right here. (A NAMED reference
|
|
// type carries its docs at the type's own declaration instead.)
|
|
checkFunctionLike(where, raw, annotation.parameters, annotation.type, false, w)
|
|
} else if (init !== undefined && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
|
|
// A named declarator type annotation (`const f: Handler = …`) hands
|
|
// the return contract to the named type; the arrow's own annotation is
|
|
// still checked when it is the only signature the reader has.
|
|
checkFunctionLike(where, raw, init.parameters, init.type, init.type === undefined && d.type !== undefined, w)
|
|
} else {
|
|
checkDescribed(where, raw, w)
|
|
}
|
|
}
|
|
return
|
|
}
|
|
if (ts.isModuleDeclaration(stmt) && ts.isIdentifier(stmt.name)) {
|
|
// A namespace merging with a documented same-name sibling (the
|
|
// Config-namespace idiom) needs no second doc block of its own.
|
|
const siblings = (byName.get(stmt.name.text) ?? []).filter(s => s !== stmt)
|
|
const merged = siblings.some(s => parseJsDoc(rawJsDoc(w.text, s)).doc !== '')
|
|
if (!merged) checkDescribed(`exported namespace '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
|
|
let body = stmt.body
|
|
let nsPrefix = `${prefix}${stmt.name.text}.`
|
|
while (body !== undefined && ts.isModuleDeclaration(body)) { // dotted `namespace A.B`
|
|
nsPrefix += `${body.name.getText(w.sf)}.`
|
|
body = body.body
|
|
}
|
|
// In an ambient (`declare`) namespace body, members are implicitly
|
|
// exported — no `export` modifier required — so the recursion must treat
|
|
// every statement as surface.
|
|
const declared = ambient
|
|
|| ((ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) : undefined)?.some(m => m.kind === ts.SyntaxKind.DeclareKeyword) ?? false)
|
|
if (body !== undefined && ts.isModuleBlock(body)) checkScope(body.statements, nsPrefix, w, declared)
|
|
return
|
|
}
|
|
if (ts.isImportEqualsDeclaration(stmt)) {
|
|
const where = `exported alias '${prefix}${stmt.name.text}'${at(stmt)}`
|
|
// An alias is a distinct exported name whose target may be a non-exported
|
|
// namespace member no walk ever visits, so it documents ITSELF — which
|
|
// matches the gate's strength only for prose-only target kinds. A
|
|
// callable, class, or namespace target carries signature or member
|
|
// contracts the alias prose cannot hold: refuse those (fail closed) and
|
|
// demand the declaration be exported directly. An unresolvable target is
|
|
// refused for the same reason.
|
|
const sym = w.checker.getSymbolAtLocation(stmt.name)
|
|
const target = sym !== undefined && (sym.flags & ts.SymbolFlags.Alias) !== 0 ? w.checker.getAliasedSymbol(sym) : sym
|
|
const RICH_TARGETS = ts.SymbolFlags.Function | ts.SymbolFlags.Class | ts.SymbolFlags.ValueModule | ts.SymbolFlags.NamespaceModule
|
|
const rich = target === undefined
|
|
|| (target.flags & RICH_TARGETS) !== 0
|
|
|| w.checker.getTypeOfSymbol(target).getCallSignatures().length > 0
|
|
if (rich) {
|
|
w.violations.push(`${where} aliases a callable, class, or namespace target whose signature/member contract the alias cannot carry; export the declaration directly instead.`)
|
|
return
|
|
}
|
|
checkDescribed(where, rawJsDoc(w.text, stmt), w)
|
|
return
|
|
}
|
|
// Fail CLOSED: an exported statement kind this dispatch does not recognize
|
|
// must never pass silently — the gate's whole promise is that unchecked
|
|
// surface cannot exist. New TypeScript export forms extend the gate here.
|
|
w.violations.push(`exported statement${at(stmt)} uses an export form verify-export-jsdoc does not handle; extend the gate.`)
|
|
}
|
|
|
|
/**
|
|
* Walk one lexical scope (file top level or a namespace body): check every
|
|
* exported declaration, resolving `export { … }` lists (no module specifier)
|
|
* to their local declarations.
|
|
* @param statements - the scope's statements.
|
|
* @param prefix - the namespace qualification for surface names ('' at top level).
|
|
* @param w - the walk state violations append to.
|
|
* @param ambient - whether this scope is ambient (`declare` namespace or a declaration file), where members export implicitly.
|
|
*/
|
|
function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk, ambient: boolean): void {
|
|
const byName = new Map<string, ts.Statement[]>()
|
|
const overloadSigs = new Set<string>()
|
|
const add = (name: string, stmt: ts.Statement): void => {
|
|
byName.set(name, [...(byName.get(name) ?? []), stmt])
|
|
}
|
|
for (const stmt of statements) {
|
|
if (ts.isFunctionDeclaration(stmt)) {
|
|
if (stmt.name) add(stmt.name.text, stmt)
|
|
if (!stmt.body && stmt.name) overloadSigs.add(stmt.name.text)
|
|
} else if (ts.isClassDeclaration(stmt) || ts.isInterfaceDeclaration(stmt)
|
|
|| ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt)) {
|
|
if (stmt.name) add(stmt.name.text, stmt)
|
|
} else if (ts.isModuleDeclaration(stmt) && ts.isIdentifier(stmt.name)) {
|
|
add(stmt.name.text, stmt)
|
|
} else if (ts.isVariableStatement(stmt)) {
|
|
for (const d of stmt.declarationList.declarations) {
|
|
if (ts.isIdentifier(d.name)) add(d.name.text, stmt)
|
|
}
|
|
}
|
|
}
|
|
// Two-phase dispatch. Phase one accumulates WHICH statements are surface
|
|
// and, for a variable statement reached by name (an export list or a
|
|
// default-export identifier), which of its declarators the exports actually
|
|
// name — `null` marks the whole statement as surface (a direct `export`
|
|
// modifier, or an ambient scope). Requests for the same statement merge:
|
|
// `null` absorbs any name set, and name sets union, so
|
|
// `export { a }; export { b }` over one `const a = …, b = …` checks both
|
|
// declarators while a never-exported sibling stays out of the surface.
|
|
// Phase two runs each surfaced statement exactly once. (Checking a
|
|
// statement eagerly per request would either re-check on the second list or
|
|
// — deduplicated — silently drop the second list's declarators.)
|
|
const requested = new Map<ts.Statement, Set<string> | null>()
|
|
const request = (stmt: ts.Statement, name: string | null): void => {
|
|
const prior = requested.get(stmt)
|
|
if (name === null || prior === null) {
|
|
requested.set(stmt, null)
|
|
return
|
|
}
|
|
requested.set(stmt, prior === undefined ? new Set([name]) : prior.add(name))
|
|
}
|
|
for (const stmt of statements) {
|
|
if (ts.isModuleDeclaration(stmt)
|
|
&& (ts.isStringLiteral(stmt.name) || (stmt.flags & ts.NodeFlags.GlobalAugmentation) !== 0)) {
|
|
continue // `declare module '…'` / `declare global` augmentation: not an export of this package
|
|
}
|
|
if (ts.isExportDeclaration(stmt)) {
|
|
if (stmt.moduleSpecifier) continue // re-export: the defining module is walked on its own
|
|
if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
|
|
for (const el of stmt.exportClause.elements) {
|
|
const local = (el.propertyName ?? el.name).text
|
|
for (const decl of byName.get(local) ?? []) request(decl, local)
|
|
// a name with no local declaration is an imported binding re-exported
|
|
// without a specifier — its defining module is walked on its own
|
|
}
|
|
}
|
|
continue
|
|
}
|
|
if (ts.isExportAssignment(stmt)) {
|
|
if (stmt.isExportEquals) {
|
|
// `export =` has no ESM consumer surface in this repo and the walk
|
|
// cannot classify its operand's shape; refuse rather than fail open.
|
|
w.violations.push(`export-equals assignment (${pointer(w.rel, w.sf, stmt)}) is not a gate-supported export form; use ESM named exports.`)
|
|
continue
|
|
}
|
|
const where = `default export (${pointer(w.rel, w.sf, stmt)})`
|
|
const expr = unwrapExpression(stmt.expression)
|
|
if (ts.isIdentifier(expr)) {
|
|
for (const decl of byName.get(expr.text) ?? []) request(decl, expr.text)
|
|
} else if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) {
|
|
checkFunctionLike(where, rawJsDoc(w.text, stmt), expr.parameters, expr.type, false, w)
|
|
} else {
|
|
checkDescribed(where, rawJsDoc(w.text, stmt), w)
|
|
}
|
|
continue
|
|
}
|
|
if (isExported(stmt) || (ambient && !ts.isImportDeclaration(stmt))) request(stmt, null)
|
|
}
|
|
for (const stmt of statements) {
|
|
const only = requested.get(stmt)
|
|
if (only !== undefined) checkDecl(stmt, prefix, overloadSigs, byName, ambient, w, only)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Compiler options for the walk's program. The real repo hands over its
|
|
* tsconfig.base.json (whose `paths` map resolves cross-package imports to
|
|
* source, so heritage-member lookups see seam types); a fixture root without
|
|
* one gets `noLib` + no `@types` — fixtures are single-file and
|
|
* self-contained, nothing in the walk resolves a lib symbol, and default-lib
|
|
* parsing is ~99% of per-program cost (it made the fixture spec time out
|
|
* under CI coverage instrumentation). Emit-side options are stripped: the
|
|
* walk never emits or asks for diagnostics, it only binds types on demand.
|
|
* @param scanRoot - the root being scanned.
|
|
* @returns compiler options for ts.createProgram.
|
|
*/
|
|
function loadCompilerOptions(scanRoot: string): ts.CompilerOptions {
|
|
const cfgPath = resolve(scanRoot, 'tsconfig.base.json')
|
|
if (!existsSync(cfgPath)) return { skipLibCheck: true, noLib: true, types: [] }
|
|
const cfg = ts.readConfigFile(cfgPath, ts.sys.readFile.bind(ts.sys)) as { config?: unknown }
|
|
const parsed = ts.parseJsonConfigFileContent(cfg.config ?? {}, ts.sys, scanRoot)
|
|
return {
|
|
...parsed.options,
|
|
noEmit: true,
|
|
composite: false,
|
|
declaration: false,
|
|
declarationMap: false,
|
|
sourceMap: false,
|
|
incremental: false,
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Walk every non-vendored package source file and collect JSDoc-completeness
|
|
* violations for its module-level exports. Returns findings instead of
|
|
* throwing so tests assert on the list; the CLI entry turns a non-empty list
|
|
* into exit 1.
|
|
* @param scanRoot - the repo root to scan; tests pass a fixture dir.
|
|
* @returns every violation, in file order, one human-readable line each.
|
|
*/
|
|
export function collectExportJsdocViolations(scanRoot: string = root): string[] {
|
|
const violations: string[] = []
|
|
const rels = globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).sort()
|
|
const program = ts.createProgram(rels.map(rel => resolve(scanRoot, rel)), loadCompilerOptions(scanRoot))
|
|
const checker = program.getTypeChecker()
|
|
for (const rel of rels) {
|
|
const sf = program.getSourceFile(resolve(scanRoot, rel))
|
|
if (!sf) continue // program root files always resolve; guard for narrowing
|
|
// A script-style declaration file (no imports/exports) is one big ambient
|
|
// scope; a module-style .d.ts still honors explicit export modifiers.
|
|
checkScope(sf.statements, '', { rel, sf, text: sf.text, checker, violations }, sf.isDeclarationFile && !ts.isExternalModule(sf))
|
|
}
|
|
return violations
|
|
}
|
|
|
|
/** CLI entry: list every violation and exit 1, or confirm a clean surface. */
|
|
function main(): void {
|
|
const violations = collectExportJsdocViolations()
|
|
if (violations.length === 0) {
|
|
console.log('verify-export-jsdoc: every exported name on the package surface is documented.')
|
|
return
|
|
}
|
|
console.error(`verify-export-jsdoc: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):`)
|
|
for (const v of violations) console.error(` ${v}`)
|
|
process.exit(1)
|
|
}
|
|
|
|
// Run only when invoked as a script, not when imported by a test.
|
|
if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
|
|
main()
|
|
}
|