@am_shork/attest 0.1.0

package/dist/core/validator.js

@@ -0,0 +1,73 @@
+// Structural validation + anti-drift heuristic (design §5.3, §6).
+// Graded reporting: ERROR / WARNING / INFO, each with file + line + fix hint.
+/**
+ * Static structural validation (design §5.3). Emits ERROR-level issues for:
+ * - orphan-test: a scenario covers an unknown requirement id
+ * - uncovered-requirement: a requirement has no scenario
+ * - unbound-param: a statement placeholder has no matching param
+ */
+export function validateStructure(registry, plan) {
+    const issues = [];
+    const knownIds = new Set(Object.keys(registry));
+    const coveredIds = new Set(plan.scenarios.map((s) => s.reqId));
+    // orphan-test: covers a requirement that does not exist.
+    for (const s of plan.scenarios) {
+        if (!knownIds.has(s.reqId)) {
+            issues.push({
+                level: 'ERROR',
+                code: 'orphan-test',
+                file: s.file,
+                line: s.line,
+                message: `scenario "${s.name}" 覆蓋未知需求 "${s.reqId}"。請在 registry 新增，或修正 ID。`,
+            });
+        }
+    }
+    // uncovered-requirement: intent exists but no scenario attests it.
+    for (const id of knownIds) {
+        if (!coveredIds.has(id)) {
+            issues.push({
+                level: 'ERROR',
+                code: 'uncovered-requirement',
+                message: `需求 "${id}" 沒有任何 scenario 佐證。加一個 scenario 或標記為 deferred。`,
+            });
+        }
+    }
+    // unbound-param: statement uses {param} but params does not define it.
+    for (const [id, req] of Object.entries(registry)) {
+        for (const m of req.statement.matchAll(/\{(\w+)\}/g)) {
+            const name = m[1];
+            if (!(name in req.params)) {
+                issues.push({
+                    level: 'ERROR',
+                    code: 'unbound-param',
+                    message: `需求 "${id}" 的 statement 用了 {${name}}，但 params 未定義它。`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Weak anti-drift heuristic (design §6, mechanism 3). Emits an INFO when a
+ * scenario covers a requirement that has params but the scenario does not
+ * reference them — a place a drifting hardcoded literal could hide.
+ */
+export function detectPotentialDrift(registry, plan, refs) {
+    return plan.scenarios.flatMap((s) => {
+        const req = registry[s.reqId];
+        const hasParams = req !== undefined && Object.keys(req.params).length > 0;
+        const referencesParams = refs.some((r) => r.reqId === s.reqId && r.scenario === s.name);
+        return hasParams && !referencesParams
+            ? [
+                {
+                    level: 'INFO',
+                    code: 'possible-drift',
+                    file: s.file,
+                    line: s.line,
+                    message: `scenario "${s.name}" 覆蓋 ${s.reqId}（有 params）卻未引用它，可能藏有會漂移的硬寫字面值。`,
+                },
+            ]
+            : [];
+    });
+}
+//# sourceMappingURL=validator.js.map

package/dist/core/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { requirement, scenario } from './runtime.js';
+export { defineRequirements, delta } from './core/registry.js';
+export type { RegistryDelta } from './core/registry.js';
+export type { Requirement, Registry, ParsedScenario, AttestPlan, Level, Issue, } from './core/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,UAAU,EACV,KAAK,EACL,KAAK,GACN,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// Sole public entry point for the `attest` package (design §10).
+// Users import only from here; core/ internals are intentionally not exported.
+export { requirement, scenario } from './runtime.js';
+export { defineRequirements, delta } from './core/registry.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,+EAA+E;AAE/E,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Group scenarios that verify one requirement. The describe block is named
+ * `[id]` so runtime coverage can be reconstructed from the task tree (§5.4).
+ */
+export declare function requirement(id: string, body: () => void): void;
+/**
+ * Declare a single verifiable scenario. Must be nested inside requirement().
+ * The assertion itself is delegated to Vitest `it` (design §3).
+ */
+export declare function scenario(name: string, fn: () => void | Promise<void>): void;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAU9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAK3E"}

package/dist/runtime.js

@@ -0,0 +1,32 @@
+// Authoring runtime API: requirement() / scenario() (design §3).
+// Pure delegation to Vitest; no in-process coverage singleton — coverage is
+// reconstructed from the Vitest task tree instead (design §5.4).
+import { describe, it } from 'vitest';
+let currentReqId = null;
+/**
+ * Group scenarios that verify one requirement. The describe block is named
+ * `[id]` so runtime coverage can be reconstructed from the task tree (§5.4).
+ */
+export function requirement(id, body) {
+    describe(`[${id}]`, () => {
+        const prev = currentReqId;
+        currentReqId = id;
+        try {
+            body();
+        }
+        finally {
+            currentReqId = prev;
+        }
+    });
+}
+/**
+ * Declare a single verifiable scenario. Must be nested inside requirement().
+ * The assertion itself is delegated to Vitest `it` (design §3).
+ */
+export function scenario(name, fn) {
+    if (!currentReqId) {
+        throw new Error(`scenario("${name}") 必須巢狀在 requirement(...) 內`);
+    }
+    it(name, fn);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,4EAA4E;AAC5E,iEAAiE;AAEjE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAEtC,IAAI,YAAY,GAAkB,IAAI,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,IAAgB;IACtD,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE;QACvB,MAAM,IAAI,GAAG,YAAY,CAAC;QAC1B,YAAY,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,EAAE,CAAC;QACT,CAAC;gBAAS,CAAC;YACT,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,EAA8B;IACnE,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,6BAA6B,CAAC,CAAC;IAClE,CAAC;IACD,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@am_shork/attest",
+  "version": "0.1.0",
+  "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
+  "type": "module",
+  "packageManager": "pnpm@10.28.0",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/Pseudorca/attest.git"
+  },
+  "homepage": "https://gitlab.com/Pseudorca/attest#readme",
+  "bugs": {
+    "url": "https://gitlab.com/Pseudorca/attest/-/issues"
+  },
+  "bin": {
+    "attest": "bin/attest.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "prepack": "pnpm run build",
+    "attest": "node bin/attest.js",
+    "check:self": "node bin/attest.js check self",
+    "verify:self": "node bin/attest.js verify self",
+    "cover:self": "node bin/attest.js cover self"
+  },
+  "keywords": [
+    "tdd",
+    "spec",
+    "requirements",
+    "drift",
+    "vitest"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "typescript": "^5.5.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0",
+    "vitest": "^2.0.0 || ^3.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "@types/node": "^20.19.0",
+    "eslint": "^9.9.0",
+    "typescript-eslint": "^8.2.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}