@entelekheia/ref-id 0.1.0

package/dist/validators.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// The one registry that maps a NAME the spec uses to behaviour: the owning validators (by
+// `dispatch.<type>.validator`), the ways a delegated string is formed (by `dispatch.<type>.delegate`),
+// the refinement range constraints (by `refinements.<key>.range`), and the policies this package
+// implements (`unknownKey`, `repeatedKey`). A validator or delegate name the spec uses and this file
+// does not know degrades to `uncovered`; a range or policy name it does not know is a version
+// mismatch and is refused loudly, because silently skipping a constraint is the drift the guardrail
+// forbids.
+import { PackageURL } from "packageurl-js";
+import { FIELD, pattern } from "./grammar.js";
+import { SpecVersionError } from "./spec.js";
+const validators = {
+    "package-url": (_spec, _entry, delegated) => {
+        try {
+            return { ok: true, canonical: PackageURL.fromString(delegated).toString() };
+        }
+        catch {
+            return { ok: false };
+        }
+    },
+    "declared-name": (spec, entry, delegated) => ({ ok: pattern(spec, entry.pattern ?? "").test(delegated) }),
+};
+/** How `dispatch.<type>.delegate` forms the delegated string, and whether a producer may pass the format's own scheme back in. */
+const delegators = {
+    "type-prefixed": { form: (type, locator) => `${type}${FIELD}${locator}`, foldsType: true },
+    verbatim: { form: (_type, locator) => locator, foldsType: false },
+};
+/** The constraints a refinement may declare beyond its pattern, by the name `refinements.<key>.range` uses. */
+const ranges = {
+    ascending: (value, boundSeparator) => {
+        const bounds = value.split(boundSeparator).map(Number);
+        return bounds.length < 2 || (bounds[0] ?? 0) <= (bounds[1] ?? 0);
+    },
+};
+/** The policies this package implements, by the name the spec declares them under. */
+const policies = { unknownKey: "carry-through", repeatedKey: "malformed" };
+const policiesChecked = new WeakSet();
+/** Refuses a spec whose declared policies or range names are ones this package does not implement. */
+export function assertImplemented(spec) {
+    if (policiesChecked.has(spec)) {
+        return;
+    }
+    const declared = [
+        ["grammar.state.unknownKey", spec.grammar.state.unknownKey],
+        ["unknownRefinement", spec.unknownRefinement],
+        ["grammar.state.repeatedKey", spec.grammar.state.repeatedKey],
+        ["grammar.fragment.repeatedKey", spec.grammar.fragment.repeatedKey],
+    ];
+    for (const [field, value] of declared) {
+        const implemented = field.endsWith("repeatedKey") ? policies.repeatedKey : policies.unknownKey;
+        if (value !== implemented) {
+            throw new SpecVersionError(`spec.${field} declares ${JSON.stringify(value)}; this package implements only ${JSON.stringify(implemented)}`);
+        }
+    }
+    for (const [key, refinement] of Object.entries(spec.refinements)) {
+        if (refinement.range !== undefined && !Object.hasOwn(ranges, refinement.range)) {
+            throw new SpecVersionError(`spec.refinements.${key}.range declares ${JSON.stringify(refinement.range)}, which this package does not implement`);
+        }
+    }
+    policiesChecked.add(spec);
+}
+/** The string handed to the validator, or undefined when the type is not dispatched or its delegate mode is unknown here. */
+export function delegatedString(spec, type, locator) {
+    const entry = spec.dispatch[type];
+    const delegator = entry ? delegators[entry.delegate] : undefined;
+    return delegator ? delegator.form(type, locator) : undefined;
+}
+/** True when a producer may pass the intact format string (`pkg:npm/x`) as the locator of this type. */
+export function foldsType(spec, type) {
+    const entry = spec.dispatch[type];
+    return entry ? (delegators[entry.delegate]?.foldsType ?? false) : false;
+}
+/** Runs the owning validator, or undefined when the spec names one this package does not implement. */
+export function validateLocator(spec, entry, delegated) {
+    const validator = validators[entry.validator];
+    return validator ? validator(spec, entry, delegated) : undefined;
+}
+/** True when the value satisfies the refinement's declared range constraint (or it declares none). */
+export function rangeHolds(refinement, value) {
+    if (refinement.range === undefined) {
+        return true;
+    }
+    const check = ranges[refinement.range];
+    return check ? check(value, refinement.boundSeparator ?? "") : true;
+}
+//# sourceMappingURL=validators.js.map

package/dist/validators.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@entelekheia/ref-id",
+  "version": "0.1.0",
+  "description": "The ref: identifier scheme \u2014 a specification published as data with conformance vectors, and the package that consumes it.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "spec"
+  ],
+  "scripts": {
+    "prebuild": "mkdir -p spec && cp ../../spec/ref-id.json ../../spec/ref-id.json.sha256 spec/",
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "mkdir -p spec && cp ../../spec/ref-id.json ../../spec/ref-id.json.sha256 spec/",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/entelekheia-ai/ref-id.git",
+    "directory": "packages/ref-id"
+  },
+  "dependencies": {
+    "packageurl-js": "^2.0.1"
+  }
+}