| name | annotation-writer |
| description | Write correct @spec JSDoc annotations in TypeScript/JavaScript source files to link code to specgraph spec documents. |
Add @spec annotations to source files so specgraph's AnnotationProvider can scan them and produce E0 evidence.
Annotation syntax
Or inline:
Multiple specs on one component — use separate blocks:
export class AuthService { ... }
Relation types
| Annotation | Evidence relation | Use when |
|---|
@implements | IMPLEMENTS | This code directly implements the spec |
@verifies | VERIFIED_BY | This is a test that verifies the spec |
@satisfies | IMPLEMENTS | Alias for @implements |
Placement rules
- Functions/methods — annotate the JSDoc block immediately above the function.
- Classes — annotate the class JSDoc block; all public methods are covered.
- Files — annotate the top-level
export if the whole file implements one spec.
- Tests — use
@verifies on test functions or describe blocks.
TypeScript examples
export function validateToken(token: string): Payload { ... }
describe('todo filters', () => { ... });
JavaScript (CommonJS) example
module.exports.rateLimiter = function(req, res, next) { ... };
Rules
- Use the exact spec ID as it appears in the spec file frontmatter (
id: field).
- One annotation per
@spec tag — do not chain multiple @spec tags in one block.
ComponentName after @implements is free text — use something meaningful to the reader.- After adding annotations, run
specgraph verify to confirm the claims are detected.
- If claims are not appearing, check that the file extension is in
annotationProvider.extensions in .specgraph/config.json (defaults: .ts, .js, .tsx, .jsx, .mjs, .cjs).
