@thymian/plugin-sampler 0.3.0-canary.20261007-e6cb8dc → 0.3.0-canary.20261007-cdbe1d3

package/dist/sampler-paths.d.ts

@@ -0,0 +1,19 @@
+export type SamplerPaths = {
+    /** The per-sampler root, `<cwd>/.thymian/sampler` by default. */
+    root: string;
+    /** The committed type surface. Regenerated wholesale. */
+    generatedDir: string;
+    /** The recursive hook tree the loader scans. */
+    hooksDir: string;
+    /** The tsconfig `init` scaffolds once and thereafter never touches. */
+    tsconfigPath: string;
+};
+/**
+ * The single source of truth for every sampler path.
+ *
+ * `path` is the plugin option. It named the v1 samples tree, which no longer
+ * exists; it now names the sampler root, so a project that kept its sampler
+ * somewhere other than `.thymian/sampler` keeps one option to say so.
+ */
+export declare function resolveSamplerPaths(cwd: string, path?: string): SamplerPaths;
+//# sourceMappingURL=sampler-paths.d.ts.map

package/dist/sampler-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler-paths.d.ts","sourceRoot":"","sources":["../src/sampler-paths.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG;IACzB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,CAa5E"}

package/dist/sampler-paths.js

@@ -0,0 +1,22 @@
+import { isAbsolute, join } from 'node:path';
+/**
+ * The single source of truth for every sampler path.
+ *
+ * `path` is the plugin option. It named the v1 samples tree, which no longer
+ * exists; it now names the sampler root, so a project that kept its sampler
+ * somewhere other than `.thymian/sampler` keeps one option to say so.
+ */
+export function resolveSamplerPaths(cwd, path) {
+    const root = path
+        ? isAbsolute(path)
+            ? path
+            : join(cwd, path)
+        : join(cwd, '.thymian', 'sampler');
+    return {
+        root,
+        generatedDir: join(root, 'generated'),
+        hooksDir: join(root, 'hooks'),
+        tsconfigPath: join(root, 'tsconfig.json'),
+    };
+}
+//# sourceMappingURL=sampler-paths.js.map

package/dist/sampler-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler-paths.js","sourceRoot":"","sources":["../src/sampler-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAa7C;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,IAAa;IAC5D,MAAM,IAAI,GAAG,IAAI;QACf,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAChB,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC;QACnB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAErC,OAAO;QACL,IAAI;QACJ,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;QACrC,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;QAC7B,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC;KAC1C,CAAC;AACJ,CAAC"}

package/dist/selectors/nearest-paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Paths that share `value`'s longest literal prefix, as message lines.
+ *
+ * Walks the prefix from the longest down to the shortest, so the reader is
+ * pointed at the narrowest subtree that actually has anything in it rather
+ * than at the whole description. No fuzzy matching: it would add a
+ * dependency and make the ordering unexplainable.
+ *
+ * Shared between a vacuous filter path value and a Selector whose path is a
+ * typo — the same prefix walk, so the two diagnostics agree on what "near"
+ * means instead of carrying two guesses that could disagree.
+ */
+export declare function nearestPathHints(value: string, paths: readonly string[]): string[];
+//# sourceMappingURL=nearest-paths.d.ts.map

package/dist/selectors/nearest-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearest-paths.d.ts","sourceRoot":"","sources":["../../src/selectors/nearest-paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,MAAM,EAAE,CAoBV"}

package/dist/selectors/nearest-paths.js

@@ -0,0 +1,32 @@
+const MAX_NEAR_PATHS = 5;
+/**
+ * Paths that share `value`'s longest literal prefix, as message lines.
+ *
+ * Walks the prefix from the longest down to the shortest, so the reader is
+ * pointed at the narrowest subtree that actually has anything in it rather
+ * than at the whole description. No fuzzy matching: it would add a
+ * dependency and make the ordering unexplainable.
+ *
+ * Shared between a vacuous filter path value and a Selector whose path is a
+ * typo — the same prefix walk, so the two diagnostics agree on what "near"
+ * means instead of carrying two guesses that could disagree.
+ */
+export function nearestPathHints(value, paths) {
+    const segments = value.split('/');
+    for (let depth = segments.length - 1; depth > 0; depth--) {
+        const prefix = `${segments.slice(0, depth).join('/')}/`;
+        const candidates = paths
+            .filter((path) => path.startsWith(prefix))
+            .slice(0, MAX_NEAR_PATHS);
+        if (candidates.length > 0) {
+            return [
+                `Paths under "${prefix}" are:`,
+                ...candidates.map((path) => `"${path}"`),
+            ];
+        }
+    }
+    return [
+        `No path in the loaded API description begins with "${segments[1] ? `/${segments[1]}` : value}".`,
+    ];
+}
+//# sourceMappingURL=nearest-paths.js.map

package/dist/selectors/nearest-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearest-paths.js","sourceRoot":"","sources":["../../src/selectors/nearest-paths.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAa,EACb,KAAwB;IAExB,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAElC,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QACxD,MAAM,UAAU,GAAG,KAAK;aACrB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACzC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QAE5B,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACL,gBAAgB,MAAM,QAAQ;gBAC9B,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC;aACzC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,sDAAsD,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI;KAClG,CAAC;AACJ,CAAC"}

package/dist/selectors/path-glob.d.ts

@@ -0,0 +1,94 @@
+/**
+ * # The path-glob grammar — FROZEN
+ *
+ * A glob is a string compared against a path as the transaction catalog spells
+ * it: beginning with `/`, already carrying the API description's server base
+ * path, with `{param}` in template form. Both sides are compared **segment by
+ * segment**, where a segment is a maximal run of characters containing no `/`.
+ *
+ * ```ebnf
+ * glob            = segment , { "/" , segment } , [ "/" , deep-wildcard ] ;
+ * segment         = wildcard | literal-segment ;
+ * wildcard        = "*" ;                  (* the WHOLE segment, never part *)
+ * deep-wildcard   = "**" ;                 (* final position only *)
+ * literal-segment = { literal-char } ;     (* matched byte-for-byte *)
+ * literal-char    = ? any character except "/" ? ;
+ * ```
+ *
+ * ## The decisions (all of them explicit, all of them frozen)
+ *
+ * 1. **`*` matches exactly one whole segment.** It never matches part of a
+ *    segment. `/foo*` is therefore **not a legal glob** — it is a segment whose
+ *    literal text happens to be `foo*`, which matches no real path, and which
+ *    `validate` reports as "matches nothing". It is deliberately *not* a
+ *    separate "malformed glob" diagnostic: one diagnostic for "this names
+ *    nothing" is the whole promise, and a second class of error would have to
+ *    be kept in sync with the first.
+ * 2. **`*` matches exactly one segment — never zero.** `/users/*` does not
+ *    match `/users`, and does not match `/users/` (whose trailing segment is
+ *    the empty string).
+ * 3. **`*` never crosses `/`.** `/users/*` does not match `/users/1/orders`.
+ * 4. **A trailing `**` matches one *or more* segments.** `/admin/**` matches
+ *    `/admin/users` and `/admin/users/42/roles`, and does **not** match
+ *    `/admin` itself. A user who wants both writes two entries. This is the
+ *    decision most likely to be argued later, so: it is one-or-more, and the
+ *    reason is that `/admin/**` reads as "everything *under* /admin", and a
+ *    zero-or-more reading makes `{ path: '/admin/**' }` silently a superset of
+ *    `{ path: '/admin' }` — two different intents spelled the same way.
+ * 5. **`**` is legal only as the final segment.** Leading and mid-path `**`
+ *    are out; mid-path `**` is deferred. A `**` anywhere else is, again, just a
+ *    literal segment that matches nothing.
+ * 6. **`{id}` — and any other brace text — is a literal.** Real paths contain
+ *    `{id}`, `{launchId}` and so on, because the loader keeps the template
+ *    form. A glob spells them exactly as the path does. Braces are **not**
+ *    metacharacters and never will be in this grammar.
+ * 7. **Matching is case-sensitive and exact.** `/Users/*` does not match
+ *    `/users/1`. No normalisation, no trailing-slash tolerance, no percent
+ *    decoding.
+ * 8. **A glob containing no metacharacter is just an exact path.** It has to
+ *    equal a path the catalog holds, and it is validated by the same rule as
+ *    every other glob: does it name at least one path.
+ * 9. **Anchoring.** A glob is matched against the whole path string, anchored
+ *    at both ends — there is no implicit prefix or suffix wildcard. The string
+ *    it is anchored against carries the server base path, so on a description
+ *    whose server is `https://api.example.com/v1`, the glob for the spec's own
+ *    `/admin/**` example is `/v1/admin/**`.
+ *
+ * ## Deliberately excluded — this list is closed
+ *
+ * `?` (single character); character classes (`[a-z]`); brace alternation
+ * (`{a,b}`); regular expressions of any kind; leading or mid-path `**`;
+ * negation inside a glob (exclusion is `not:`, a filter-level feature);
+ * case-insensitive matching; escaping (there is no escape character, because
+ * there is nothing to escape: `*` in a literal position is already just a
+ * character that matches nothing); and **globbing on any filter field other
+ * than `path`** — `method`, `status`, `statusClass`, `requestMediaType` and
+ * `responseMediaType` stay closed unions.
+ *
+ * Anything not on the "in" list is out.
+ *
+ * The semantics above are stated as data in `bench/glob-corpus.ts`, and
+ * {@link matchesPathGlob} is checked against that corpus and nothing else.
+ */
+/**
+ * Whether `glob` names `path`.
+ *
+ * Written directly from the decision list above, iteratively rather than
+ * recursively, so that reading it against the grammar is a one-pass job.
+ */
+export declare function matchesPathGlob(glob: string, path: string): boolean;
+/**
+ * Whether a path value carries a wildcard at all (decision 8).
+ *
+ * Only used for the wording of a diagnostic: an exact path that names nothing
+ * and a glob that names nothing are the same fault, but "no path is spelled
+ * that way" and "that glob matches nothing" are not the same sentence.
+ *
+ * Any `*` counts, not only a whole-segment one. `/v1/launch*` is a glob the
+ * user wrote — `PathGlob` accepts it and the grammar says so — it is just a
+ * glob that names nothing, because decision 1 makes `launch*` a literal
+ * segment. Testing for a whole-segment `*` instead told that user no path was
+ * *spelled* `/v1/launch*`, which is true and unhelpful.
+ */
+export declare function hasWildcard(value: string): boolean;
+//# sourceMappingURL=path-glob.d.ts.map

package/dist/selectors/path-glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-glob.d.ts","sourceRoot":"","sources":["../../src/selectors/path-glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAkDnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD"}

package/dist/selectors/path-glob.js

@@ -0,0 +1,136 @@
+/**
+ * # The path-glob grammar — FROZEN
+ *
+ * A glob is a string compared against a path as the transaction catalog spells
+ * it: beginning with `/`, already carrying the API description's server base
+ * path, with `{param}` in template form. Both sides are compared **segment by
+ * segment**, where a segment is a maximal run of characters containing no `/`.
+ *
+ * ```ebnf
+ * glob            = segment , { "/" , segment } , [ "/" , deep-wildcard ] ;
+ * segment         = wildcard | literal-segment ;
+ * wildcard        = "*" ;                  (* the WHOLE segment, never part *)
+ * deep-wildcard   = "**" ;                 (* final position only *)
+ * literal-segment = { literal-char } ;     (* matched byte-for-byte *)
+ * literal-char    = ? any character except "/" ? ;
+ * ```
+ *
+ * ## The decisions (all of them explicit, all of them frozen)
+ *
+ * 1. **`*` matches exactly one whole segment.** It never matches part of a
+ *    segment. `/foo*` is therefore **not a legal glob** — it is a segment whose
+ *    literal text happens to be `foo*`, which matches no real path, and which
+ *    `validate` reports as "matches nothing". It is deliberately *not* a
+ *    separate "malformed glob" diagnostic: one diagnostic for "this names
+ *    nothing" is the whole promise, and a second class of error would have to
+ *    be kept in sync with the first.
+ * 2. **`*` matches exactly one segment — never zero.** `/users/*` does not
+ *    match `/users`, and does not match `/users/` (whose trailing segment is
+ *    the empty string).
+ * 3. **`*` never crosses `/`.** `/users/*` does not match `/users/1/orders`.
+ * 4. **A trailing `**` matches one *or more* segments.** `/admin/**` matches
+ *    `/admin/users` and `/admin/users/42/roles`, and does **not** match
+ *    `/admin` itself. A user who wants both writes two entries. This is the
+ *    decision most likely to be argued later, so: it is one-or-more, and the
+ *    reason is that `/admin/**` reads as "everything *under* /admin", and a
+ *    zero-or-more reading makes `{ path: '/admin/**' }` silently a superset of
+ *    `{ path: '/admin' }` — two different intents spelled the same way.
+ * 5. **`**` is legal only as the final segment.** Leading and mid-path `**`
+ *    are out; mid-path `**` is deferred. A `**` anywhere else is, again, just a
+ *    literal segment that matches nothing.
+ * 6. **`{id}` — and any other brace text — is a literal.** Real paths contain
+ *    `{id}`, `{launchId}` and so on, because the loader keeps the template
+ *    form. A glob spells them exactly as the path does. Braces are **not**
+ *    metacharacters and never will be in this grammar.
+ * 7. **Matching is case-sensitive and exact.** `/Users/*` does not match
+ *    `/users/1`. No normalisation, no trailing-slash tolerance, no percent
+ *    decoding.
+ * 8. **A glob containing no metacharacter is just an exact path.** It has to
+ *    equal a path the catalog holds, and it is validated by the same rule as
+ *    every other glob: does it name at least one path.
+ * 9. **Anchoring.** A glob is matched against the whole path string, anchored
+ *    at both ends — there is no implicit prefix or suffix wildcard. The string
+ *    it is anchored against carries the server base path, so on a description
+ *    whose server is `https://api.example.com/v1`, the glob for the spec's own
+ *    `/admin/**` example is `/v1/admin/**`.
+ *
+ * ## Deliberately excluded — this list is closed
+ *
+ * `?` (single character); character classes (`[a-z]`); brace alternation
+ * (`{a,b}`); regular expressions of any kind; leading or mid-path `**`;
+ * negation inside a glob (exclusion is `not:`, a filter-level feature);
+ * case-insensitive matching; escaping (there is no escape character, because
+ * there is nothing to escape: `*` in a literal position is already just a
+ * character that matches nothing); and **globbing on any filter field other
+ * than `path`** — `method`, `status`, `statusClass`, `requestMediaType` and
+ * `responseMediaType` stay closed unions.
+ *
+ * Anything not on the "in" list is out.
+ *
+ * The semantics above are stated as data in `bench/glob-corpus.ts`, and
+ * {@link matchesPathGlob} is checked against that corpus and nothing else.
+ */
+/**
+ * Whether `glob` names `path`.
+ *
+ * Written directly from the decision list above, iteratively rather than
+ * recursively, so that reading it against the grammar is a one-pass job.
+ */
+export function matchesPathGlob(glob, path) {
+    const globSegments = glob.split('/');
+    const pathSegments = path.split('/');
+    const deep = globSegments.at(-1) === '**';
+    // Decision 5: `**` is legal only as the final segment. Anywhere else it is a
+    // literal segment, which is what the equality branch below gives it.
+    const fixed = deep ? globSegments.slice(0, -1) : globSegments;
+    // Decision 4: a trailing `**` needs one or more segments to consume, so the
+    // path must be strictly longer than the fixed prefix. Without a trailing
+    // `**` the two must have the same number of segments — decisions 2 and 3.
+    if (deep
+        ? pathSegments.length <= fixed.length
+        : pathSegments.length !== fixed.length) {
+        return false;
+    }
+    for (const [index, globSegment] of fixed.entries()) {
+        const pathSegment = pathSegments[index] ?? '';
+        if (globSegment === '*') {
+            // Decision 2: exactly one segment, never zero. An empty segment is not a
+            // segment.
+            if (pathSegment === '') {
+                return false;
+            }
+            continue;
+        }
+        // Decisions 1, 6, 7, 8: everything else is literal, compared exactly.
+        if (globSegment !== pathSegment) {
+            return false;
+        }
+    }
+    // Decision 4 again, for what the tail actually holds. The length test above
+    // proves the tail is non-empty as a list, not that it holds a segment: a
+    // path written with a trailing slash splits to one final empty string, so
+    // `/admin/**` matched `/admin/` and `/**` matched `/`. `*` already refuses an
+    // empty segment above, and "one or more segments" has to mean the same thing
+    // in both spellings.
+    if (deep && pathSegments.slice(fixed.length).every((s) => s === '')) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Whether a path value carries a wildcard at all (decision 8).
+ *
+ * Only used for the wording of a diagnostic: an exact path that names nothing
+ * and a glob that names nothing are the same fault, but "no path is spelled
+ * that way" and "that glob matches nothing" are not the same sentence.
+ *
+ * Any `*` counts, not only a whole-segment one. `/v1/launch*` is a glob the
+ * user wrote — `PathGlob` accepts it and the grammar says so — it is just a
+ * glob that names nothing, because decision 1 makes `launch*` a literal
+ * segment. Testing for a whole-segment `*` instead told that user no path was
+ * *spelled* `/v1/launch*`, which is true and unhelpful.
+ */
+export function hasWildcard(value) {
+    return value.includes('*');
+}
+//# sourceMappingURL=path-glob.js.map

package/dist/selectors/path-glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-glob.js","sourceRoot":"","sources":["../../src/selectors/path-glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY;IACxD,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE1C,6EAA6E;IAC7E,qEAAqE;IACrE,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IAE9D,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,IACE,IAAI;QACF,CAAC,CAAC,YAAY,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM;QACrC,CAAC,CAAC,YAAY,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EACxC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACnD,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAE9C,IAAI,WAAW,KAAK,GAAG,EAAE,CAAC;YACxB,yEAAyE;YACzE,WAAW;YACX,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;gBACvB,OAAO,KAAK,CAAC;YACf,CAAC;YAED,SAAS;QACX,CAAC;QAED,sEAAsE;QACtE,IAAI,WAAW,KAAK,WAAW,EAAE,CAAC;YAChC,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,qBAAqB;IACrB,IAAI,IAAI,IAAI,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/selectors/selector-errors.d.ts

@@ -0,0 +1,17 @@
+import { ThymianBaseError, type ThymianHttpTransaction } from '@thymian/core';
+/**
+ * Two transactions in the loaded format render the same selector. Fail-fast:
+ * nothing is dropped, overwritten or resolved "last wins". This is the one hard
+ * error at catalog build — rendering itself never rejects.
+ */
+export declare function selectorCollisionError(selector: string, first: ThymianHttpTransaction, second: ThymianHttpTransaction): ThymianBaseError;
+/**
+ * A well-formed selector that names no transaction in the loaded format. The
+ * near-miss candidates are supplied by the catalog, which is the only thing that
+ * knows what is loaded. A dangling selector is never auto-rebound to a
+ * "close enough" transaction.
+ */
+export declare function unknownSelectorError(selector: string, suggestions: string[]): ThymianBaseError;
+/** The value is not a selector at all. */
+export declare function malformedSelectorError(value: string, hints?: string[]): ThymianBaseError;
+//# sourceMappingURL=selector-errors.d.ts.map

package/dist/selectors/selector-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-errors.d.ts","sourceRoot":"","sources":["../../src/selectors/selector-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAGhB,KAAK,sBAAsB,EAE5B,MAAM,eAAe,CAAC;AA2HvB;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,sBAAsB,EAC7B,MAAM,EAAE,sBAAsB,GAC7B,gBAAgB,CAalB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EAAE,GACpB,gBAAgB,CASlB;AAED,0CAA0C;AAC1C,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,EAAO,GACnB,gBAAgB,CAalB"}

package/dist/selectors/selector-errors.js

@@ -0,0 +1,139 @@
+import { ThymianBaseError, thymianRequestToOrigin, } from '@thymian/core';
+/**
+ * The selector grammar, written the way the reference pages write it. Kept next
+ * to the errors so the diagnostic and the parser cannot drift apart in wording.
+ */
+const SELECTOR_GRAMMAR = 'METHOD SP path [ SP "(" requestMediaType ")" ] SP "->" SP status [ SP "(" responseMediaType ")" ]';
+const SELECTOR_EXAMPLE = 'POST /astronauts (application/json) -> 201 (application/json)';
+function locationToString(location) {
+    if (!location) {
+        return undefined;
+    }
+    const file = 'path' in location ? location.path : location.uri;
+    if (!location.position) {
+        return file;
+    }
+    return `${file}:${location.position.line}:${location.position.column}`;
+}
+/**
+ * `thymianRequestToOrigin` runs the origin through `normalizeUrl`, which throws
+ * when `protocol://host:port` is not a URL — an OpenAPI `servers` entry like
+ * `file:///tmp/api` leaves `host` empty. That failure must never replace the
+ * diagnostic the user actually needs to read.
+ *
+ * `normalizeUrl` returns `url.toString()`, which appends the empty path as a
+ * trailing slash. These sentences end in a period, so the slash is dropped: an
+ * origin has none.
+ */
+function originOf(req) {
+    try {
+        const origin = thymianRequestToOrigin(req);
+        return origin.endsWith('/') ? origin.slice(0, -1) : origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The source pointer a diagnostic prints.
+ *
+ * `sourceName` is typed `string` on every node and edge but is not one at
+ * runtime: `plugin-openapi` defaults it to `document.info.title`, the config
+ * never requires an explicit name, and a missing `title` only warns. So it can
+ * arrive `''` or `undefined`, and an unnamed source is named as such — it must
+ * never render as `Source ""`, and it must never turn the diagnostic the user
+ * needs into a `TypeError`.
+ */
+function describeSource(sourceName, origin, location) {
+    const where = locationToString(location);
+    return ((sourceName
+        ? `Source "${sourceName}" describes it`
+        : 'An unnamed source describes it') +
+        (origin ? ` at ${origin}` : '') +
+        (where ? ` (${where}).` : '.'));
+}
+/**
+ * Names a transaction from its RESPONSE node, and takes the location from the
+ * same producer — never from a mixture.
+ *
+ * Of the three carriers of a `sourceName`, the response node is the only one
+ * that belongs to the description that actually declared this transaction. A
+ * request node is deduped *across* sources, because `sourceName` sits in core's
+ * ignored hash properties, and the transaction edge then inherits that deduped
+ * name. A response node cannot be shared while a collision exists — its id is
+ * derived from the request id and the response's semantic hash, so two sources
+ * share it only when the whole transaction is identical, and then it merges and
+ * there is nothing to collide.
+ *
+ * Mixing carriers is what prints source A's name over source B's file: core
+ * rewrites an edge's `sourceName` but leaves the producer's `sourceLocation`
+ * alone. The edge is consulted for the location only, where it is the same
+ * producer's as the response node's.
+ */
+function describeTransaction(transaction) {
+    return describeSource(transaction.thymianRes.sourceName, originOf(transaction.thymianReq), transaction.thymianRes.sourceLocation ??
+        transaction.transaction.sourceLocation);
+}
+/**
+ * The advice every collision gets, whichever kind it is.
+ *
+ * There is deliberately **no** same-source/cross-source classification. Telling
+ * the two apart needs a per-specification identity, and the graph carries only a
+ * source *name*: it defaults to `document.info.title` and is never required, so
+ * a staging and a production description of one API — the flagship cross-source
+ * cause — are indistinguishable by any name-based test, an unnamed description
+ * is indistinguishable from every other unnamed one, and a request node deduped
+ * across sources hands its name to an edge that never declared it.
+ *
+ * So the advice names both remedies without asserting which applies. The two
+ * lines above it already print each transaction's source and, where the
+ * description carries one, its file and position — the evidence a classifier
+ * never had, handed to the one reader who can use it.
+ */
+const COLLISION_ADVICE = [
+    'A selector is host-stripped and carries no query parameters or headers, so two transactions collide whenever they agree on method, path, status and media types — whether they come from one description or two.',
+    'If the two lines above point at different documents, load those sources separately — a source-discriminator syntax does not exist.',
+    'If they point at one document, give the two operations distinct paths, methods, statuses or media types.',
+];
+/**
+ * Two transactions in the loaded format render the same selector. Fail-fast:
+ * nothing is dropped, overwritten or resolved "last wins". This is the one hard
+ * error at catalog build — rendering itself never rejects.
+ */
+export function selectorCollisionError(selector, first, second) {
+    return new ThymianBaseError(`Two transactions resolve to the same selector "${selector}".`, {
+        name: 'SelectorCollisionError',
+        ref: 'https://thymian.dev/references/errors/selector-collision-error/',
+        suggestions: [
+            describeTransaction(first),
+            describeTransaction(second),
+            ...COLLISION_ADVICE,
+        ],
+    });
+}
+/**
+ * A well-formed selector that names no transaction in the loaded format. The
+ * near-miss candidates are supplied by the catalog, which is the only thing that
+ * knows what is loaded. A dangling selector is never auto-rebound to a
+ * "close enough" transaction.
+ */
+export function unknownSelectorError(selector, suggestions) {
+    return new ThymianBaseError(`No transaction matches the selector "${selector}".`, {
+        name: 'UnknownSelectorError',
+        ref: 'https://thymian.dev/references/errors/unknown-selector-error/',
+        suggestions,
+    });
+}
+/** The value is not a selector at all. */
+export function malformedSelectorError(value, hints = []) {
+    return new ThymianBaseError(`"${value}" is not a valid transaction selector.`, {
+        name: 'MalformedSelectorError',
+        ref: 'https://thymian.dev/references/errors/malformed-selector-error/',
+        suggestions: [
+            ...hints,
+            `Write a selector as ${SELECTOR_GRAMMAR}.`,
+            `For example: "${SELECTOR_EXAMPLE}".`,
+        ],
+    });
+}
+//# sourceMappingURL=selector-errors.js.map

package/dist/selectors/selector-errors.js.map

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

package/dist/selectors/selector.d.ts

@@ -0,0 +1,55 @@
+import { canonicalPath, encodeMediaType, encodeMethod, encodePath, formatRequestSelector, formatResponseSelector, formatSelector, type Selector, selectorForTransaction } from '@thymian/core';
+/**
+ * The selector grammar, plugin side: everything that reads a selector.
+ *
+ * **Rendering lives in `@thymian/core`** (`selector/render-selector.ts`) and is
+ * re-exported here, because a selector is two things at once — the sampler's
+ * *address* of a Transaction and the application's *label* for one — and every
+ * surface core prints has to render the same grammar the sampler resolves
+ * (ADR-0022). What stays here is what only an address needs: parsing back,
+ * near-miss diagnostics and the catalog's ordering.
+ *
+ * The reader below is the inverse of core's encoders. The two are one grammar
+ * split across two packages, so the round-trip property — every rendered
+ * selector parses, and parses back to what it was rendered from — is the test
+ * that keeps them honest.
+ */
+export { canonicalPath, encodeMediaType, encodeMethod, encodePath, formatRequestSelector, formatResponseSelector, formatSelector, type Selector, selectorForTransaction, };
+export type SelectorParts = {
+    method: string;
+    path: string;
+    requestMediaType?: string;
+    status: number;
+    responseMediaType?: string;
+};
+/**
+ * Total order on selectors, by UTF-16 code unit.
+ *
+ * Deliberately not `localeCompare`: the catalog's order is the order of the
+ * generated type surface, and a locale-sensitive comparison would make the
+ * committed types depend on the machine that generated them.
+ */
+export declare function compareSelectors(a: Selector, b: Selector): number;
+/**
+ * Parses a selector back into its components.
+ *
+ * For DIAGNOSTICS ONLY. Resolution is a map lookup
+ * (`TransactionCatalog.resolve`); a parse happens only after a miss, to decide
+ * whether the value was malformed or merely unknown. Do not move a parse onto
+ * the happy path.
+ */
+export declare function parseSelector(value: string): SelectorParts;
+/** Whether `value` is a syntactically well-formed selector. */
+export declare function isSelector(value: string): boolean;
+/**
+ * The suggestions a malformed selector's diagnostic carries — the grammar,
+ * an example, and a canonical-form guess when the value is close. Never
+ * throws.
+ *
+ * Reads `malformedSelectorError`'s own message composition rather than
+ * duplicating it, so a hook-target diagnostic for a malformed Selector and
+ * the error `catalog.resolve` throws for one typed on the CLI say exactly the
+ * same thing — one grammar, one set of hints, two call sites.
+ */
+export declare function malformedSelectorHints(value: string): string[];
+//# sourceMappingURL=selector.d.ts.map

package/dist/selectors/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/selectors/selector.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EAEV,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,KAAK,QAAQ,EAEb,sBAAsB,EACvB,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,KAAK,QAAQ,EACb,sBAAsB,GACvB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAwGF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEjE;AA2HD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAQ1D;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAI9D"}