@abseed/spectra-drift-check 0.1.0 → 0.3.0

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Luke Pezet
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,5 +1,5 @@
 Spectra
-Copyright 2026 lpezet
+Copyright 2026 Luke Pezet
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 this project except in compliance with the License. You may obtain a copy of the

package/dist/check.d.ts

@@ -1,5 +1,5 @@
-import type { Marker, Snapshot } from './implements.js';
-export type DriftFindingKind = 'no-snapshot' | 'no-markers' | 'malformed-marker' | 'unknown-term' | 'unimplemented-term';
+import type { Marker, Snapshot, VerifyMarker } from './implements.js';
+export type DriftFindingKind = 'no-snapshot' | 'no-markers' | 'malformed-marker' | 'unknown-term' | 'unimplemented-term' | 'unknown-expectation' | 'unverified-expectation';
 export interface DriftFinding {
     kind: DriftFindingKind;
     message: string;
@@ -9,10 +9,11 @@ export interface DriftFinding {
  * file, not a missing service, so it fails hard rather than skipping (a green run that checked
  * nothing is the outcome worth refusing).
  */
-export declare function checkDrift(markers: Marker[], snapshot: Snapshot | null): DriftFinding[];
+export declare function checkDrift(markers: Marker[], snapshot: Snapshot | null, verifyMarkers?: VerifyMarker[]): DriftFinding[];
 /**
  * Read markers from `srcDir` and the snapshot at `snapshotPath`, and run the check. The convenience
  * a consumer project's test calls: `const { ok, findings } = driftCheck({ srcDir, snapshotPath })`.
+ * `// verifies:` markers are read from the same tree (including its test files).
  */
 export declare function driftCheck(opts: {
     srcDir: string;

package/dist/check.js

@@ -5,14 +5,23 @@
  * consumer project turns it into a one-line test in whatever runner it already uses (see the README).
  * Empty list means the code and the committed snapshot are in sync.
  *
- * What it catches, and what it deliberately cannot: a malformed marker, a marker naming a term the
- * glossary no longer has, and a term (entity/function/event) nothing implements. It cannot catch a
- * term whose *spec was rewritten* — the marker still names it and still looks right. That is what the
- * per-term `hash` in the snapshot is for: refreshing the file makes `git diff specs.snapshot.json`
- * name the terms that moved, so the check fails loud for structure and review catches the rest.
+ * It checks two correspondences, symmetrically:
+ *
+ * - **Terms ↔ code.** A malformed `implements:` marker, a marker naming a term the glossary no longer
+ *   has, and a term (entity/function/event) nothing implements.
+ * - **Expectations ↔ tests (GH #96).** A malformed `verifies:` marker, a marker naming an expectation
+ *   the glossary no longer has, and a *functional* expectation no test verifies. Non-functional
+ *   expectations are exempt — they are properties of a running build, checked by driving it, not by a
+ *   test phrased in glossary vocabulary.
+ *
+ * What it deliberately cannot catch: a term whose *spec was rewritten*, or an expectation whose
+ * *wording changed* — the marker still names it and still looks right. That is what the per-term and
+ * per-expectation `hash` in the snapshot is for: refreshing the file makes `git diff
+ * specs.snapshot.json` name what moved, so the check fails loud for structure and review catches the
+ * rest.
  */
 import { existsSync } from 'node:fs';
-import { implementersOf, readMarkers, readSnapshot } from './implements.js';
+import { implementersOf, readMarkers, readSnapshot, readVerifyMarkers } from './implements.js';
 /** Terms that must be implemented by code. attribute-types are value shapes carried by other terms. */
 const NEEDS_IMPLEMENTING = new Set(['entity', 'function', 'event']);
 /**
@@ -20,7 +29,7 @@ const NEEDS_IMPLEMENTING = new Set(['entity', 'function', 'event']);
  * file, not a missing service, so it fails hard rather than skipping (a green run that checked
  * nothing is the outcome worth refusing).
  */
-export function checkDrift(markers, snapshot) {
+export function checkDrift(markers, snapshot, verifyMarkers = []) {
     if (!snapshot) {
         return [{ kind: 'no-snapshot', message: 'No specs.snapshot.json — run export_specs and commit the result.' }];
     }
@@ -50,15 +59,43 @@ export function checkDrift(markers, snapshot) {
             findings.push({ kind: 'unimplemented-term', message: `${term.name} (${term.type}) — nothing implements it; an implementation pass is due` });
         }
     }
+    // Expectations ↔ tests. A snapshot exported before expectations existed has none, so this is a
+    // no-op there; the field is optional for exactly that reason.
+    const expectations = snapshot.expectations ?? [];
+    const knownExpectations = new Set(expectations.map((expectation) => expectation.id));
+    for (const marker of verifyMarkers) {
+        if (marker.malformed.length > 0) {
+            findings.push({
+                kind: 'malformed-marker',
+                message: `${marker.file}:${marker.line} — not expectation ids: ${marker.malformed.join(', ')} (a verifies: marker names ids like e-001; put prose on the next line)`,
+            });
+        }
+        for (const id of marker.ids) {
+            if (!knownExpectations.has(id)) {
+                findings.push({ kind: 'unknown-expectation', message: `${marker.file}:${marker.line} — verifies "${id}", not a live expectation in the glossary (renamed, retired, or a typo)` });
+            }
+        }
+    }
+    const verified = new Set(verifyMarkers.flatMap((marker) => marker.ids));
+    for (const expectation of expectations) {
+        // Only functional expectations become an example test that a // verifies: marker names. A
+        // non-functional one is a property of a build; an invariant verifies as a property over all
+        // states (the verify-loop's job, not a single marker) — so both are exempt from this check.
+        if (expectation.kind === 'functional' && !verified.has(expectation.id)) {
+            findings.push({ kind: 'unverified-expectation', message: `${expectation.id} (functional) — no // verifies: marker; nothing tests that the code satisfies it` });
+        }
+    }
     return findings;
 }
 /**
  * Read markers from `srcDir` and the snapshot at `snapshotPath`, and run the check. The convenience
  * a consumer project's test calls: `const { ok, findings } = driftCheck({ srcDir, snapshotPath })`.
+ * `// verifies:` markers are read from the same tree (including its test files).
  */
 export function driftCheck(opts) {
     const markers = readMarkers(opts.srcDir);
+    const verifyMarkers = readVerifyMarkers(opts.srcDir);
     const snapshot = existsSync(opts.snapshotPath) ? readSnapshot(opts.snapshotPath) : null;
-    const findings = checkDrift(markers, snapshot);
+    const findings = checkDrift(markers, snapshot, verifyMarkers);
     return { ok: findings.length === 0, findings };
 }

package/dist/implements.d.ts

@@ -6,8 +6,23 @@ export interface Marker {
     /** Entries that are not bare identifiers — reported instead of silently ignored. */
     malformed: string[];
 }
+export interface VerifyMarker {
+    /** Path relative to the scanned root. */
+    file: string;
+    line: number;
+    /** Expectation ids this test claims to verify. */
+    ids: string[];
+    /** Entries that are not expectation ids — reported instead of silently ignored. */
+    malformed: string[];
+}
 /** Every `// implements:` marker under `root`, with the terms it names and any malformed entries. */
 export declare function readMarkers(root: string): Marker[];
+/**
+ * Every `// verifies:` marker under `root`, with the expectation ids it names and any malformed
+ * entries. Unlike {@link readMarkers}, this scans `.test.ts` files too — the verifying test is the
+ * thing being marked.
+ */
+export declare function readVerifyMarkers(root: string): VerifyMarker[];
 export interface TermRecord {
     name: string;
     type: string;

package/dist/implements.js

@@ -1,43 +1,58 @@
 /**
- * Reading the `// implements:` markers and the committed glossary snapshot.
+ * Reading the `// implements:` and `// verifies:` markers and the committed glossary snapshot.
  *
- * The markers are the only link from a term back to the code responsible for it, and a comment
- * nothing checks is a comment that rots. This makes them parseable so a test can fail when the
- * glossary and the code drift apart — a term with no implementer, or a marker naming a term that no
- * longer exists.
+ * The markers are the only link from a term (or an expectation) back to the code responsible for it,
+ * and a comment nothing checks is a comment that rots. This makes them parseable so a test can fail
+ * when the glossary and the code drift apart — a term with no implementer, or a marker naming a term
+ * that no longer exists.
  *
- * The grammar is deliberately strict: `// implements:` followed by comma-separated bare identifiers
- * and nothing else. Trailing prose would have to be guessed at, so anything that is not an identifier
- * is reported rather than skipped. Put the prose on the next line.
+ * Two marker kinds, and their differences are deliberate:
+ *
+ * - **`// implements: <Term>`** links code to a term. Terms are implemented by *production* code, so
+ *   these are read from source and `.test.ts` files are skipped. Grammar: comma-separated bare
+ *   identifiers (`Task`, `createTask`).
+ * - **`// verifies: <expectation-id>`** links a *test* to the expectation it exercises (GH #96). These
+ *   live in test files by nature, so the scan *includes* `.test.ts`. Expectation ids are hyphenated
+ *   (`e-001`), which the identifier grammar forbids — so they get their own id grammar.
+ *
+ * Either grammar is strict: comma-separated tokens and nothing else. Trailing prose would have to be
+ * guessed at, so anything that is not a valid token is reported rather than skipped. Put the prose on
+ * the next line.
  *
  * (Ported from the reference `app/` on the `backup/todo-app` branch, now a package a consumer project
  * depends on so the check ships with Spectra rather than being copied per project.)
  */
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-const MARKER = /^\s*(?:\/\/|\*)\s*implements:\s*(.*)$/;
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** An expectation id like `e-001` — a lowercase-ish prefix, a hyphen, then digits. */
+const EXPECTATION_ID = /^[A-Za-z]+-\d+$/;
 const SOURCE = /\.tsx?$/;
-function sourceFiles(dir, root = dir) {
+function sourceFiles(dir, includeTests, root = dir) {
     const found = [];
     for (const entry of readdirSync(dir).sort()) {
         const full = path.join(dir, entry);
         if (statSync(full).isDirectory()) {
-            found.push(...sourceFiles(full, root));
+            found.push(...sourceFiles(full, includeTests, root));
         }
-        else if (SOURCE.test(entry) && !entry.endsWith('.test.ts')) {
+        else if (SOURCE.test(entry) && (includeTests || !entry.endsWith('.test.ts'))) {
             found.push(path.relative(root, full));
         }
     }
     return found;
 }
-/** Every `// implements:` marker under `root`, with the terms it names and any malformed entries. */
-export function readMarkers(root) {
+/**
+ * Every `<keyword>:` marker under `root`, split into valid entries and malformed ones. Shared by
+ * both marker kinds so the file-walk and the comment grammar (`//` or a `*` JSDoc continuation) live
+ * in one place; the caller supplies what a valid entry looks like and whether tests are scanned.
+ */
+function collect(root, keyword, valid, includeTests) {
+    const line = new RegExp(String.raw `^\s*(?:\/\/|\*)\s*${keyword}:\s*(.*)$`);
     const markers = [];
-    for (const file of sourceFiles(root)) {
+    for (const file of sourceFiles(root, includeTests)) {
         const lines = readFileSync(path.join(root, file), 'utf8').split('\n');
-        lines.forEach((line, index) => {
-            const match = MARKER.exec(line);
+        lines.forEach((text, index) => {
+            const match = line.exec(text);
             if (!match)
                 return;
             const entries = match[1]
@@ -47,13 +62,35 @@ export function readMarkers(root) {
             markers.push({
                 file,
                 line: index + 1,
-                terms: entries.filter((entry) => IDENTIFIER.test(entry)),
-                malformed: entries.filter((entry) => !IDENTIFIER.test(entry)),
+                entries: entries.filter((entry) => valid.test(entry)),
+                malformed: entries.filter((entry) => !valid.test(entry)),
             });
         });
     }
     return markers;
 }
+/** Every `// implements:` marker under `root`, with the terms it names and any malformed entries. */
+export function readMarkers(root) {
+    return collect(root, 'implements', IDENTIFIER, false).map((m) => ({
+        file: m.file,
+        line: m.line,
+        terms: m.entries,
+        malformed: m.malformed,
+    }));
+}
+/**
+ * Every `// verifies:` marker under `root`, with the expectation ids it names and any malformed
+ * entries. Unlike {@link readMarkers}, this scans `.test.ts` files too — the verifying test is the
+ * thing being marked.
+ */
+export function readVerifyMarkers(root) {
+    return collect(root, 'verifies', EXPECTATION_ID, true).map((m) => ({
+        file: m.file,
+        line: m.line,
+        ids: m.entries,
+        malformed: m.malformed,
+    }));
+}
 /**
  * The glossary as this project sees it — a committed file (`export_specs` writes it), not a directory
  * somewhere else. `specs/` is not reachable from a standalone copy of the project, nor from inside

package/dist/index.d.ts

@@ -3,8 +3,9 @@
  * implements it, as a small package a consumer project depends on.
  *
  * A project keeps a `specs.snapshot.json` (written by @coder's `export_specs`, committed with the
- * code) and `// implements: <Term>` markers in its source. This checks the two agree — offline, with
- * no coordinator running — so it works both in a bare copy of the project and inside @coder's sandbox.
+ * code), `// implements: <Term>` markers in its source, and `// verifies: <expectation-id>` markers
+ * on the tests that exercise its expectations. This checks all three agree — offline, with no
+ * coordinator running — so it works both in a bare copy of the project and inside @coder's sandbox.
  * It replaces the per-project copied files the check used to be (see `backup/todo-app`).
  *
  * Usage in a consumer project's test (framework-agnostic core; example in vitest):
@@ -15,8 +16,11 @@
  *     const { ok, findings } = driftCheck({ srcDir: 'src', snapshotPath: 'specs.snapshot.json' })
  *     expect(ok, findings.map((f) => f.message).join('\n')).toBe(true)
  *   })
+ *
+ * A test that exercises expectation `e-001` marks itself with `// verifies: e-001` (in the test file),
+ * the same way production code marks `// implements: <Term>`.
  */
-export { readMarkers, readSnapshot, implementersOf } from './implements.js';
-export type { Marker, Snapshot, TermRecord, ExpectationRecord } from './implements.js';
+export { readMarkers, readVerifyMarkers, readSnapshot, implementersOf } from './implements.js';
+export type { Marker, VerifyMarker, Snapshot, TermRecord, ExpectationRecord } from './implements.js';
 export { checkDrift, driftCheck } from './check.js';
 export type { DriftFinding, DriftFindingKind } from './check.js';

package/dist/index.js

@@ -3,8 +3,9 @@
  * implements it, as a small package a consumer project depends on.
  *
  * A project keeps a `specs.snapshot.json` (written by @coder's `export_specs`, committed with the
- * code) and `// implements: <Term>` markers in its source. This checks the two agree — offline, with
- * no coordinator running — so it works both in a bare copy of the project and inside @coder's sandbox.
+ * code), `// implements: <Term>` markers in its source, and `// verifies: <expectation-id>` markers
+ * on the tests that exercise its expectations. This checks all three agree — offline, with no
+ * coordinator running — so it works both in a bare copy of the project and inside @coder's sandbox.
  * It replaces the per-project copied files the check used to be (see `backup/todo-app`).
  *
  * Usage in a consumer project's test (framework-agnostic core; example in vitest):
@@ -15,6 +16,9 @@
  *     const { ok, findings } = driftCheck({ srcDir: 'src', snapshotPath: 'specs.snapshot.json' })
  *     expect(ok, findings.map((f) => f.message).join('\n')).toBe(true)
  *   })
+ *
+ * A test that exercises expectation `e-001` marks itself with `// verifies: e-001` (in the test file),
+ * the same way production code marks `// implements: <Term>`.
  */
-export { readMarkers, readSnapshot, implementersOf } from './implements.js';
+export { readMarkers, readVerifyMarkers, readSnapshot, implementersOf } from './implements.js';
 export { checkDrift, driftCheck } from './check.js';

package/package.json

@@ -1,17 +1,23 @@
 {
   "name": "@abseed/spectra-drift-check",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Offline drift check between a Spectra glossary and the code that implements it.",
-  "type": "module",
   "license": "Apache-2.0",
   "author": "lpezet",
-  "homepage": "https://github.com/lpezet/spectra/tree/main/packages/drift-check",
+  "homepage": "https://github.com/ABSeedAI/spectra/tree/main/packages/drift-check",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lpezet/spectra.git",
+    "url": "git+https://github.com/ABSeedAI/spectra.git",
     "directory": "packages/drift-check"
   },
-  "keywords": ["spectra", "spec-driven", "glossary", "drift-check", "vitest"],
+  "keywords": [
+    "spectra",
+    "spec-driven",
+    "glossary",
+    "drift-check",
+    "vitest"
+  ],
+  "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -20,20 +26,9 @@
       "default": "./dist/index.js"
     }
   },
-  "files": ["dist", "NOTICE"],
   "sideEffects": false,
+  "dependencies": {},
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "devDependencies": {
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
   }
 }