@supersigil/eslint-plugin 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @supersigil/eslint-plugin
+
+ESLint plugin for validating [Supersigil](https://supersigil.org) criterion refs.
+
+## Installation
+
+```sh
+npm install -D @supersigil/eslint-plugin
+```
+
+Requires the `supersigil` CLI to be available on `PATH`.
+
+## Usage
+
+Add the plugin to your ESLint flat config:
+
+```js
+import supersigil from '@supersigil/eslint-plugin'
+
+export default [
+  supersigil.configs.recommended,
+  // ...your other configs
+]
+```
+
+Or configure manually:
+
+```js
+import supersigil from '@supersigil/eslint-plugin'
+
+export default [
+  {
+    plugins: { '@supersigil': supersigil },
+    rules: {
+      '@supersigil/valid-criterion-ref': 'error',
+    },
+  },
+]
+```
+
+## Rules
+
+### `valid-criterion-ref`
+
+Validates that criterion refs passed to `verifies()` or listed in `meta.verifies` arrays point to criteria that actually exist in your specifications.
+
+Reports errors for:
+
+- **Malformed refs** — missing the `#` separator (e.g. `'auth/req'` instead of `'auth/req#req-1-1'`)
+- **Unknown documents** — the document part of the ref doesn't match any specification
+- **Unknown criteria** — the criterion doesn't exist in the referenced document
+
+The rule loads valid refs from the `supersigil` CLI on first run and caches them for the ESLint session. If the CLI is unavailable, the rule silently disables itself.
+
+## License
+
+[MIT](../../LICENSE-MIT) OR [Apache-2.0](../../LICENSE-APACHE)

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const plugin: {
+    rules: {
+        'valid-criterion-ref': import("eslint").Rule.RuleModule;
+    };
+    configs: Record<string, unknown>;
+};
+export default plugin;
+//# 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":"AAEA,QAAA,MAAM,MAAM;;;;aAIK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CACvC,CAAA;AAYD,eAAe,MAAM,CAAA"}

package/dist/index.js

@@ -0,0 +1,142 @@
+// src/rules/valid-criterion-ref.ts
+import { execFileSync } from "node:child_process";
+var cachedRefMap = null;
+var cachedLoadError = null;
+var loaded = false;
+var warnedBinaryUnavailable = false;
+var _testMode = false;
+var _testRefMap = null;
+var _testLoadError = null;
+function loadRefMap() {
+  if (_testMode) {
+    return { refMap: _testRefMap, error: _testLoadError };
+  }
+  if (loaded) {
+    return { refMap: cachedRefMap, error: cachedLoadError };
+  }
+  loaded = true;
+  try {
+    const output = execFileSync("supersigil", ["refs", "--all", "--format", "json"], {
+      encoding: "utf-8",
+      timeout: 3e4
+    });
+    const parsed = JSON.parse(output);
+    const entries = parsed.refs ?? parsed;
+    const refMap = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      let criteria = refMap.get(entry.doc_id);
+      if (!criteria) {
+        criteria = /* @__PURE__ */ new Set();
+        refMap.set(entry.doc_id, criteria);
+      }
+      criteria.add(entry.criterion_id);
+    }
+    cachedRefMap = refMap;
+    cachedLoadError = null;
+    return { refMap, error: null };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error loading supersigil refs";
+    cachedRefMap = null;
+    cachedLoadError = message;
+    return { refMap: null, error: message };
+  }
+}
+function validateRef(context, node, value, refMap) {
+  const hashIndex = value.indexOf("#");
+  if (hashIndex === -1) {
+    context.report({
+      node,
+      messageId: "malformed",
+      data: { ref: value }
+    });
+    return;
+  }
+  const docId = value.slice(0, hashIndex);
+  const criterionId = value.slice(hashIndex + 1);
+  const criteria = refMap.get(docId);
+  if (!criteria) {
+    context.report({
+      node,
+      messageId: "unknownDocument",
+      data: { docId, ref: value }
+    });
+    return;
+  }
+  if (!criteria.has(criterionId)) {
+    context.report({
+      node,
+      messageId: "unknownCriterion",
+      data: { criterionId, docId }
+    });
+  }
+}
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Validate Supersigil criterion refs in verifies() calls"
+    },
+    messages: {
+      malformed: "Malformed criterion ref '{{ref}}'. Expected format: document-id#criterion-id",
+      unknownDocument: "Unknown document '{{docId}}' in criterion ref '{{ref}}'",
+      unknownCriterion: "Unknown criterion '{{criterionId}}' in document '{{docId}}'"
+    },
+    schema: []
+  },
+  create(context) {
+    const { refMap, error } = loadRefMap();
+    if (refMap === null) {
+      if (error !== null && !warnedBinaryUnavailable) {
+        warnedBinaryUnavailable = true;
+        console.warn(
+          "[@supersigil/eslint-plugin] supersigil binary not available; criterion ref validation disabled"
+        );
+      }
+      return {};
+    }
+    const refs = refMap;
+    function checkStringLiteral(node) {
+      validateRef(context, node, node.value, refs);
+    }
+    return {
+      // Match: verifies('ref', 'ref', ...)
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === "verifies") {
+          for (const arg of node.arguments) {
+            if (arg.type === "Literal" && typeof arg.value === "string") {
+              checkStringLiteral(arg);
+            }
+          }
+        }
+      },
+      // Match: { verifies: ['ref', ...] } in object expressions
+      'Property[key.name="verifies"] > ArrayExpression > Literal'(node) {
+        if (typeof node.value === "string") {
+          checkStringLiteral(node);
+        }
+      }
+    };
+  }
+};
+var valid_criterion_ref_default = rule;
+
+// src/index.ts
+var plugin = {
+  rules: {
+    "valid-criterion-ref": valid_criterion_ref_default
+  },
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: {
+    "@supersigil": plugin
+  },
+  rules: {
+    "@supersigil/valid-criterion-ref": "error"
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/rules/valid-criterion-ref.ts", "../src/index.ts"],
+  "sourcesContent": ["import type { Rule } from 'eslint'\nimport { execFileSync } from 'node:child_process'\n\n// Session-level cache for the ref map (docId -> Set<criterionId>).\n// This persists for the lifetime of the ESLint process. In long-lived\n// servers (eslint_d, editor integrations), the cache is never invalidated \u2014\n// restart the ESLint server if specs change.\nlet cachedRefMap: Map<string, Set<string>> | null = null\nlet cachedLoadError: string | null = null\nlet loaded = false\nlet warnedBinaryUnavailable = false\n\n// Test seam: allow overriding the ref loading result in tests.\nlet _testMode = false\nlet _testRefMap: Map<string, Set<string>> | null = null\nlet _testLoadError: string | null = null\n\n/** @internal \u2014 test-only: inject a ref map to avoid shelling out */\nexport function _setRefMapForTesting(\n  map: Map<string, Set<string>> | null,\n): void {\n  _testMode = true\n  _testRefMap = map\n}\n\n/** @internal \u2014 test-only: simulate a load error */\nexport function _setLoadErrorForTesting(error: string | null): void {\n  _testLoadError = error\n}\n\n/** @internal \u2014 test-only: reset all overrides */\nexport function _resetTestOverrides(): void {\n  _testMode = false\n  _testRefMap = null\n  _testLoadError = null\n  warnedBinaryUnavailable = false\n}\n\ninterface RefEntry {\n  ref: string\n  doc_id: string\n  criterion_id: string\n  body_text: string\n}\n\nfunction loadRefMap(): { refMap: Map<string, Set<string>> | null; error: string | null } {\n  if (_testMode) {\n    return { refMap: _testRefMap, error: _testLoadError }\n  }\n\n  if (loaded) {\n    return { refMap: cachedRefMap, error: cachedLoadError }\n  }\n\n  loaded = true\n\n  try {\n    const output = execFileSync('supersigil', ['refs', '--all', '--format', 'json'], {\n      encoding: 'utf-8',\n      timeout: 30_000,\n    })\n\n    const parsed = JSON.parse(output)\n    const entries: RefEntry[] = parsed.refs ?? parsed\n    const refMap = new Map<string, Set<string>>()\n\n    for (const entry of entries) {\n      let criteria = refMap.get(entry.doc_id)\n      if (!criteria) {\n        criteria = new Set<string>()\n        refMap.set(entry.doc_id, criteria)\n      }\n      criteria.add(entry.criterion_id)\n    }\n\n    cachedRefMap = refMap\n    cachedLoadError = null\n    return { refMap, error: null }\n  } catch (err: unknown) {\n    const message =\n      err instanceof Error ? err.message : 'Unknown error loading supersigil refs'\n    cachedRefMap = null\n    cachedLoadError = message\n    return { refMap: null, error: message }\n  }\n}\n\nfunction validateRef(\n  context: Rule.RuleContext,\n  node: Rule.Node,\n  value: string,\n  refMap: Map<string, Set<string>>,\n): void {\n  const hashIndex = value.indexOf('#')\n\n  if (hashIndex === -1) {\n    context.report({\n      node,\n      messageId: 'malformed',\n      data: { ref: value },\n    })\n    return\n  }\n\n  const docId = value.slice(0, hashIndex)\n  const criterionId = value.slice(hashIndex + 1)\n\n  const criteria = refMap.get(docId)\n  if (!criteria) {\n    context.report({\n      node,\n      messageId: 'unknownDocument',\n      data: { docId, ref: value },\n    })\n    return\n  }\n\n  if (!criteria.has(criterionId)) {\n    context.report({\n      node,\n      messageId: 'unknownCriterion',\n      data: { criterionId, docId },\n    })\n  }\n}\n\nconst rule: Rule.RuleModule = {\n  meta: {\n    type: 'problem',\n    docs: {\n      description: 'Validate Supersigil criterion refs in verifies() calls',\n    },\n    messages: {\n      malformed:\n        \"Malformed criterion ref '{{ref}}'. Expected format: document-id#criterion-id\",\n      unknownDocument:\n        \"Unknown document '{{docId}}' in criterion ref '{{ref}}'\",\n      unknownCriterion:\n        \"Unknown criterion '{{criterionId}}' in document '{{docId}}'\",\n    },\n    schema: [],\n  },\n\n  create(context) {\n    const { refMap, error } = loadRefMap()\n\n    // When supersigil binary is unavailable, log a warning to stderr and\n    // return an empty visitor so no refs are checked. This avoids failing\n    // lint (which would happen if we used context.report at error severity).\n    if (refMap === null) {\n      if (error !== null && !warnedBinaryUnavailable) {\n        warnedBinaryUnavailable = true\n        console.warn(\n          '[@supersigil/eslint-plugin] supersigil binary not available; criterion ref validation disabled',\n        )\n      }\n      return {}\n    }\n\n    const refs = refMap\n\n    function checkStringLiteral(node: Rule.Node & { value: string }): void {\n      validateRef(context, node, node.value, refs)\n    }\n\n    return {\n      // Match: verifies('ref', 'ref', ...)\n      CallExpression(node) {\n        if (\n          node.callee.type === 'Identifier' &&\n          node.callee.name === 'verifies'\n        ) {\n          for (const arg of node.arguments) {\n            if (arg.type === 'Literal' && typeof arg.value === 'string') {\n              checkStringLiteral(arg as Rule.Node & { value: string })\n            }\n          }\n        }\n      },\n\n      // Match: { verifies: ['ref', ...] } in object expressions\n      'Property[key.name=\"verifies\"] > ArrayExpression > Literal'(\n        node: Rule.Node & { value: unknown },\n      ) {\n        if (typeof node.value === 'string') {\n          checkStringLiteral(node as Rule.Node & { value: string })\n        }\n      },\n    }\n  },\n}\n\nexport default rule\n", "import validCriterionRef from './rules/valid-criterion-ref.ts'\n\nconst plugin = {\n  rules: {\n    'valid-criterion-ref': validCriterionRef,\n  },\n  configs: {} as Record<string, unknown>,\n}\n\n// Self-referencing plugin for flat config\nplugin.configs.recommended = {\n  plugins: {\n    '@supersigil': plugin,\n  },\n  rules: {\n    '@supersigil/valid-criterion-ref': 'error',\n  },\n}\n\nexport default plugin\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/rules/valid-criterion-ref.d.ts

@@ -0,0 +1,10 @@
+import type { Rule } from 'eslint';
+/** @internal — test-only: inject a ref map to avoid shelling out */
+export declare function _setRefMapForTesting(map: Map<string, Set<string>> | null): void;
+/** @internal — test-only: simulate a load error */
+export declare function _setLoadErrorForTesting(error: string | null): void;
+/** @internal — test-only: reset all overrides */
+export declare function _resetTestOverrides(): void;
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=valid-criterion-ref.d.ts.map

package/dist/rules/valid-criterion-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-criterion-ref.d.ts","sourceRoot":"","sources":["../../src/rules/valid-criterion-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAiBlC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GACnC,IAAI,CAGN;AAED,mDAAmD;AACnD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAElE;AAED,iDAAiD;AACjD,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AA0FD,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAgEhB,CAAA;AAED,eAAe,IAAI,CAAA"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@supersigil/eslint-plugin",
+  "version": "0.1.0",
+  "description": "ESLint plugin for validating Supersigil criterion refs",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jonisavo/supersigil.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "homepage": "https://supersigil.org",
+  "bugs": "https://github.com/jonisavo/supersigil/issues",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "supersigil",
+    "specification",
+    "traceability"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.39.4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.3",
+    "@supersigil/vitest": "0.1.0"
+  },
+  "scripts": {
+    "build": "node esbuild.mjs && tsc --emitDeclarationOnly --noEmit false --outDir dist",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import validCriterionRef from './rules/valid-criterion-ref.ts'
+
+const plugin = {
+  rules: {
+    'valid-criterion-ref': validCriterionRef,
+  },
+  configs: {} as Record<string, unknown>,
+}
+
+// Self-referencing plugin for flat config
+plugin.configs.recommended = {
+  plugins: {
+    '@supersigil': plugin,
+  },
+  rules: {
+    '@supersigil/valid-criterion-ref': 'error',
+  },
+}
+
+export default plugin

package/src/rules/valid-criterion-ref.ts

@@ -0,0 +1,193 @@
+import type { Rule } from 'eslint'
+import { execFileSync } from 'node:child_process'
+
+// Session-level cache for the ref map (docId -> Set<criterionId>).
+// This persists for the lifetime of the ESLint process. In long-lived
+// servers (eslint_d, editor integrations), the cache is never invalidated —
+// restart the ESLint server if specs change.
+let cachedRefMap: Map<string, Set<string>> | null = null
+let cachedLoadError: string | null = null
+let loaded = false
+let warnedBinaryUnavailable = false
+
+// Test seam: allow overriding the ref loading result in tests.
+let _testMode = false
+let _testRefMap: Map<string, Set<string>> | null = null
+let _testLoadError: string | null = null
+
+/** @internal — test-only: inject a ref map to avoid shelling out */
+export function _setRefMapForTesting(
+  map: Map<string, Set<string>> | null,
+): void {
+  _testMode = true
+  _testRefMap = map
+}
+
+/** @internal — test-only: simulate a load error */
+export function _setLoadErrorForTesting(error: string | null): void {
+  _testLoadError = error
+}
+
+/** @internal — test-only: reset all overrides */
+export function _resetTestOverrides(): void {
+  _testMode = false
+  _testRefMap = null
+  _testLoadError = null
+  warnedBinaryUnavailable = false
+}
+
+interface RefEntry {
+  ref: string
+  doc_id: string
+  criterion_id: string
+  body_text: string
+}
+
+function loadRefMap(): { refMap: Map<string, Set<string>> | null; error: string | null } {
+  if (_testMode) {
+    return { refMap: _testRefMap, error: _testLoadError }
+  }
+
+  if (loaded) {
+    return { refMap: cachedRefMap, error: cachedLoadError }
+  }
+
+  loaded = true
+
+  try {
+    const output = execFileSync('supersigil', ['refs', '--all', '--format', 'json'], {
+      encoding: 'utf-8',
+      timeout: 30_000,
+    })
+
+    const parsed = JSON.parse(output)
+    const entries: RefEntry[] = parsed.refs ?? parsed
+    const refMap = new Map<string, Set<string>>()
+
+    for (const entry of entries) {
+      let criteria = refMap.get(entry.doc_id)
+      if (!criteria) {
+        criteria = new Set<string>()
+        refMap.set(entry.doc_id, criteria)
+      }
+      criteria.add(entry.criterion_id)
+    }
+
+    cachedRefMap = refMap
+    cachedLoadError = null
+    return { refMap, error: null }
+  } catch (err: unknown) {
+    const message =
+      err instanceof Error ? err.message : 'Unknown error loading supersigil refs'
+    cachedRefMap = null
+    cachedLoadError = message
+    return { refMap: null, error: message }
+  }
+}
+
+function validateRef(
+  context: Rule.RuleContext,
+  node: Rule.Node,
+  value: string,
+  refMap: Map<string, Set<string>>,
+): void {
+  const hashIndex = value.indexOf('#')
+
+  if (hashIndex === -1) {
+    context.report({
+      node,
+      messageId: 'malformed',
+      data: { ref: value },
+    })
+    return
+  }
+
+  const docId = value.slice(0, hashIndex)
+  const criterionId = value.slice(hashIndex + 1)
+
+  const criteria = refMap.get(docId)
+  if (!criteria) {
+    context.report({
+      node,
+      messageId: 'unknownDocument',
+      data: { docId, ref: value },
+    })
+    return
+  }
+
+  if (!criteria.has(criterionId)) {
+    context.report({
+      node,
+      messageId: 'unknownCriterion',
+      data: { criterionId, docId },
+    })
+  }
+}
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Validate Supersigil criterion refs in verifies() calls',
+    },
+    messages: {
+      malformed:
+        "Malformed criterion ref '{{ref}}'. Expected format: document-id#criterion-id",
+      unknownDocument:
+        "Unknown document '{{docId}}' in criterion ref '{{ref}}'",
+      unknownCriterion:
+        "Unknown criterion '{{criterionId}}' in document '{{docId}}'",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const { refMap, error } = loadRefMap()
+
+    // When supersigil binary is unavailable, log a warning to stderr and
+    // return an empty visitor so no refs are checked. This avoids failing
+    // lint (which would happen if we used context.report at error severity).
+    if (refMap === null) {
+      if (error !== null && !warnedBinaryUnavailable) {
+        warnedBinaryUnavailable = true
+        console.warn(
+          '[@supersigil/eslint-plugin] supersigil binary not available; criterion ref validation disabled',
+        )
+      }
+      return {}
+    }
+
+    const refs = refMap
+
+    function checkStringLiteral(node: Rule.Node & { value: string }): void {
+      validateRef(context, node, node.value, refs)
+    }
+
+    return {
+      // Match: verifies('ref', 'ref', ...)
+      CallExpression(node) {
+        if (
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'verifies'
+        ) {
+          for (const arg of node.arguments) {
+            if (arg.type === 'Literal' && typeof arg.value === 'string') {
+              checkStringLiteral(arg as Rule.Node & { value: string })
+            }
+          }
+        }
+      },
+
+      // Match: { verifies: ['ref', ...] } in object expressions
+      'Property[key.name="verifies"] > ArrayExpression > Literal'(
+        node: Rule.Node & { value: unknown },
+      ) {
+        if (typeof node.value === 'string') {
+          checkStringLiteral(node as Rule.Node & { value: string })
+        }
+      },
+    }
+  },
+}
+
+export default rule