annotation-writer

Add @spec annotations to source files so specgraph's AnnotationProvider can scan them and produce E0 evidence.

Annotation syntax

/**
 * @spec SPEC-ID @implements ComponentName
 */

Or inline:

/** @spec SPEC-ID @implements ComponentName */

Multiple specs on one component — use separate blocks:

/** @spec AUTH-001 @implements TokenValidator */
/** @spec AUTH-002 @implements SessionStore */
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
@model	MODEL	This symbol is a data model referenced by the spec
@test	VERIFIED_BY	This file is a test file for the spec
@api	IMPLEMENTS	This is an API endpoint implementing the spec

Placement rules

1. Functions/methods — annotate the JSDoc block immediately above the function.
2. Classes — annotate the class JSDoc block; all public methods are covered.
3. Files — annotate the top-level export if the whole file implements one spec.
4. Tests — use @verifies on test functions or describe blocks.

TypeScript examples

/**
 * Validates a JWT token and returns the decoded payload.
 * @spec AUTH-001 @implements TokenValidator
 */
export function validateToken(token: string): Payload { ... }

/**
 * @spec TASK-003 @verifies TodoFiltering
 */
describe('todo filters', () => { ... });

/**
 * @spec USER-002 @model UserModel
 * @spec USER-002 @api POST /users
 */
export class UserController { ... }

JavaScript (CommonJS) example

/**
 * @spec API-002 @implements RateLimiter
 */
module.exports.rateLimiter = function(req, res, next) { ... };

Multi-language support

Python, Go, Rust, Java, C#, Ruby, and most languages are supported via #, //, /* */, and """ comment styles.