@beehexa/hexasync-template-model 2608.20.18 → 2608.20.31

package/dist/templating.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The two templating layers, told apart (FR-50, Phase 1 Story 3.8).
+ *
+ * A value can carry substitution that happens when you BUILD and substitution that happens when
+ * it RUNS, and the difference decides who finds out about a mistake:
+ *
+ *   `**VariableKey**`   COMPOSE-TIME. The composer substitutes it from the project's variable
+ *                       pool. A missing one is caught at compose, by the person composing.
+ *   `{{ … }}`           RUNTIME. The worker evaluates it (Scriban) against live data. A missing
+ *                       one is caught in production, by whoever is on call.
+ *
+ * Conflating them is how a `{{env.__HSS_X}}` gets reported as an unresolved compose-time
+ * variable — noise on something that is working exactly as designed — and, worse, how a genuinely
+ * missing environment key gets the same severity as a typo'd variable name.
+ *
+ * ALL `{{ … }}` IS SCRIBAN — including inside a JSONata expression. A JSONata value may embed
+ * Scriban so the JSONata itself can be built dynamically, and the worker evaluates Scriban FIRST,
+ * then treats the result as JSONata. So there is no nested-language boundary to reason about
+ * here: a `{{ … }}` occurrence is runtime Scriban wherever it appears, and the surrounding
+ * expression language does not change that.
+ *
+ * RUNTIME IS SCRIBAN, NOT JUST `env`. The corpus holds ~30,000 `{{ … }}` occurrences: control
+ * flow (`{{end}}`), pipes (`{{ '' | uuid }}`), runtime data (`{{puller.before.X}}`) and 377
+ * distinct `env.__HSS_*` keys. The AC names the `env` case because that is the one with an
+ * external dependency, so it is classified separately rather than being the whole definition of
+ * "runtime" — a narrower model would have mislabelled the other 29,000.
+ */
+/** When the substitution happens, and therefore who discovers a mistake. */
+export type TemplatingLayer = 'compose-time' | 'runtime';
+/**
+ * What a runtime expression reaches for.
+ *
+ * `environment` is singled out because it depends on something outside the template entirely —
+ * a key that must exist in the deployment — so a later diagnostic can treat it differently from
+ * an expression over data the worker already holds.
+ */
+export type RuntimeReference = 'environment' | 'expression';
+export interface TemplateOccurrence {
+    readonly layer: TemplatingLayer;
+    /** Only meaningful for `runtime`. */
+    readonly runtimeReference?: RuntimeReference;
+    /** The full matched text, e.g. `**Foo**` or `{{ env.__HSS_X }}`. */
+    readonly raw: string;
+    /**
+     * What the occurrence names: the variable key for compose-time, the environment key for a
+     * runtime `env` reference, and the trimmed expression otherwise.
+     */
+    readonly key: string;
+    /**
+     * Every environment key this occurrence reads, for a `runtime` occurrence that reads any.
+     *
+     * `key` carries only the FIRST, because it is one string. `{{ env.A + env.B }}` is one expression
+     * reading two keys, and the whole reason `environment` is a distinct `runtimeReference` is so a
+     * later rule can ask "does this deployment define them" — which it cannot do for `env.B` if only
+     * `env.A` was ever recorded.
+     */
+    readonly environmentKeys?: readonly string[];
+    /**
+     * Offsets into the VALUE as parsed, not into the source text.
+     *
+     * Named precisely because the difference bites: a caller receives `scalar.value`, which for a
+     * quoted scalar has had escapes expanded and for a block scalar has been folded and dedented, so
+     * these offsets are not source positions and cannot be turned into one without the scalar's own
+     * range. An earlier comment promised "so a caller can map back to a source range", which is not
+     * something these offsets alone can do.
+     */
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Every templating occurrence in a value, each classified independently.
+ *
+ * Independently matters: one value can mix layers — a URL built from a compose-time variable
+ * followed by a runtime expression is both — and a classifier returning a single verdict per
+ * value would have to be wrong about one of them.
+ */
+export declare function classifyTemplating(value: string): TemplateOccurrence[];
+/** Does this value carry any compose-time substitution? */
+export declare function hasComposeTimeTemplating(value: string): boolean;
+/**
+ * Compose-time keys in a value — what a resolver needs.
+ *
+ * Runtime occurrences are deliberately absent: asking the variable pool about `{{ item.id }}`
+ * would always fail, and reporting that failure would be reporting on something the composer
+ * was never responsible for.
+ */
+export declare function composeTimeKeys(value: string): string[];
+//# sourceMappingURL=templating.d.ts.map

package/dist/templating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templating.d.ts","sourceRoot":"","sources":["../src/templating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,SAAS,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,YAAY,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,qCAAqC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAwBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAgCtE;AAED,2DAA2D;AAC3D,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQvD"}

package/dist/templating.js

@@ -0,0 +1,103 @@
+/**
+ * The two templating layers, told apart (FR-50, Phase 1 Story 3.8).
+ *
+ * A value can carry substitution that happens when you BUILD and substitution that happens when
+ * it RUNS, and the difference decides who finds out about a mistake:
+ *
+ *   `**VariableKey**`   COMPOSE-TIME. The composer substitutes it from the project's variable
+ *                       pool. A missing one is caught at compose, by the person composing.
+ *   `{{ … }}`           RUNTIME. The worker evaluates it (Scriban) against live data. A missing
+ *                       one is caught in production, by whoever is on call.
+ *
+ * Conflating them is how a `{{env.__HSS_X}}` gets reported as an unresolved compose-time
+ * variable — noise on something that is working exactly as designed — and, worse, how a genuinely
+ * missing environment key gets the same severity as a typo'd variable name.
+ *
+ * ALL `{{ … }}` IS SCRIBAN — including inside a JSONata expression. A JSONata value may embed
+ * Scriban so the JSONata itself can be built dynamically, and the worker evaluates Scriban FIRST,
+ * then treats the result as JSONata. So there is no nested-language boundary to reason about
+ * here: a `{{ … }}` occurrence is runtime Scriban wherever it appears, and the surrounding
+ * expression language does not change that.
+ *
+ * RUNTIME IS SCRIBAN, NOT JUST `env`. The corpus holds ~30,000 `{{ … }}` occurrences: control
+ * flow (`{{end}}`), pipes (`{{ '' | uuid }}`), runtime data (`{{puller.before.X}}`) and 377
+ * distinct `env.__HSS_*` keys. The AC names the `env` case because that is the one with an
+ * external dependency, so it is classified separately rather than being the whole definition of
+ * "runtime" — a narrower model would have mislabelled the other 29,000.
+ */
+/**
+ * Identifier-shaped, matching the composer's own residual-token rule.
+ *
+ * Deliberately not `\*\*.+\*\*`: markdown bold is indistinguishable from a variable token by
+ * shape alone, and a looser pattern would classify every bold phrase in a `description` as an
+ * unresolved variable. The composer already draws the line here; drawing it differently would
+ * mean two answers to one question.
+ */
+const COMPOSE_TIME_RE = /\*\*[A-Za-z0-9_]+\*\*/g;
+/** Scriban, non-greedy so adjacent expressions do not merge into one. */
+const RUNTIME_RE = /\{\{[\s\S]*?\}\}/g;
+/**
+ * A runtime expression that reads an environment key. GLOBAL — an expression can read several.
+ *
+ * The leading guard excludes `myenv.X`, but a QUOTE satisfies `[^A-Za-z0-9_.]` too, so
+ * `{{ "env.LITERAL" }}` was reported as a deployment dependency on a key that is a string literal.
+ * Quotes are now excluded explicitly.
+ */
+const ENV_REF_RE = /(?:^|[^A-Za-z0-9_.'"`])env\.([A-Za-z0-9_]+)/g;
+/**
+ * Every templating occurrence in a value, each classified independently.
+ *
+ * Independently matters: one value can mix layers — a URL built from a compose-time variable
+ * followed by a runtime expression is both — and a classifier returning a single verdict per
+ * value would have to be wrong about one of them.
+ */
+export function classifyTemplating(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return [];
+    const found = [];
+    for (const m of value.matchAll(COMPOSE_TIME_RE)) {
+        found.push({
+            layer: 'compose-time',
+            raw: m[0],
+            key: m[0].slice(2, -2),
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+    }
+    for (const m of value.matchAll(RUNTIME_RE)) {
+        const inner = m[0].slice(2, -2).trim();
+        // ALL of them. `ENV_REF_RE` was non-global and used with a single `.exec`, so a compound
+        // expression reported only its first key and every later one was invisible.
+        const envKeys = [...inner.matchAll(ENV_REF_RE)].map((e) => e[1]);
+        found.push({
+            layer: 'runtime',
+            runtimeReference: envKeys.length > 0 ? 'environment' : 'expression',
+            raw: m[0],
+            key: envKeys.length > 0 ? envKeys[0] : inner,
+            ...(envKeys.length > 0 ? { environmentKeys: envKeys } : {}),
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+    }
+    // Source order, so a caller reporting occurrences reads them the way the author wrote them.
+    return found.sort((a, b) => a.start - b.start);
+}
+/** Does this value carry any compose-time substitution? */
+export function hasComposeTimeTemplating(value) {
+    return classifyTemplating(value).some((t) => t.layer === 'compose-time');
+}
+/**
+ * Compose-time keys in a value — what a resolver needs.
+ *
+ * Runtime occurrences are deliberately absent: asking the variable pool about `{{ item.id }}`
+ * would always fail, and reporting that failure would be reporting on something the composer
+ * was never responsible for.
+ */
+export function composeTimeKeys(value) {
+    return [
+        ...new Set(classifyTemplating(value)
+            .filter((t) => t.layer === 'compose-time')
+            .map((t) => t.key)),
+    ];
+}
+//# sourceMappingURL=templating.js.map

package/dist/templating.js.map

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

package/dist/uriPath.d.ts

@@ -0,0 +1,43 @@
+/**
+ * URI path algebra — the AD-18 corollary.
+ *
+ * Core may not use `node:path` (AD-3, amended 2026-08-01): the VS Code web
+ * extension host does not provide it, and a bundler polyfill is exactly how
+ * desktop and web end up disagreeing about file identity. So core does its own
+ * path arithmetic over **normalized URI strings**: POSIX `/` only, with `.` and
+ * `..` collapsed explicitly.
+ *
+ * Pure string work. No IO, no Node builtins, no platform behaviour.
+ */
+export declare function normalizeUri(uri: string): string;
+export declare function joinUri(base: string, ...segments: readonly string[]): string;
+export declare function dirnameUri(uri: string): string;
+export declare function basenameUri(uri: string): string;
+/**
+ * True when `target` is absolute in its own right — rooted, drive-rooted, or schemed.
+ *
+ * Exported because `node:path`'s `isAbsolute` cannot answer this question for the web host: it
+ * knows nothing of `vscode-vfs://`, and on Windows it would reject a rooted POSIX path that is
+ * perfectly absolute in URI terms. This was the last of Story 1.5's 37 `path.*` call sites, and
+ * it had to move before `resolveMdIncludes` could follow the rest of the compose logic into core.
+ *
+ * ### The drive letter (reported 2026-08-08)
+ *
+ * It answered FALSE for `C:\docs\notes.md`, which is as absolute as a path gets. `merge.ts` asks
+ * this question at both `!md[…]` resolution sites — `isAbsoluteUri(ref) ? ref : resolveUri(base,
+ * ref)` — so an author on Windows writing an absolute include had it joined onto the project's base
+ * directory instead, producing `D:/project/C:/docs/notes.md` and an `ENOENT` naming a path nobody
+ * wrote. On Linux the same include starts with `/` and was always answered correctly, which is why
+ * only a Windows test run found it.
+ */
+export declare function isAbsoluteUri(target: string): boolean;
+export declare function resolveUri(base: string, target: string): string;
+export declare function relativeUri(from: string, to: string): string;
+/**
+ * The escape guard (AC 5). True only when `child` is strictly inside `parent`.
+ *
+ * Segment-aware on purpose: a `startsWith` check would accept `rootsibling/x`
+ * for parent `root` and happily write outside the install target.
+ */
+export declare function isInsideUri(parent: string, child: string): boolean;
+//# sourceMappingURL=uriPath.d.ts.map

package/dist/uriPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uriPath.d.ts","sourceRoot":"","sources":["../src/uriPath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkDH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM5E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAa5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAUlE"}

package/dist/uriPath.js

@@ -0,0 +1,151 @@
+/**
+ * URI path algebra — the AD-18 corollary.
+ *
+ * Core may not use `node:path` (AD-3, amended 2026-08-01): the VS Code web
+ * extension host does not provide it, and a bundler polyfill is exactly how
+ * desktop and web end up disagreeing about file identity. So core does its own
+ * path arithmetic over **normalized URI strings**: POSIX `/` only, with `.` and
+ * `..` collapsed explicitly.
+ *
+ * Pure string work. No IO, no Node builtins, no platform behaviour.
+ */
+/**
+ * `c:/…` — a Windows absolute path, which is ROOTED WITHOUT a leading slash.
+ *
+ * The one shape this file's "POSIX `/` only" model does not otherwise describe. Every caller has
+ * already folded backslashes to `/` before this is tested, so only the forward form appears here.
+ *
+ * A single letter followed by `:/` cannot be a URI scheme in this codebase's terms — `splitPrefix`
+ * and `isAbsoluteUri` both test the `scheme://` form FIRST, so `c://host/x` is still read as a
+ * scheme with an authority rather than as a drive.
+ */
+const DRIVE_ROOT = /^[a-zA-Z]:\//;
+/** Splits `scheme://authority`, or a Windows drive root (if any), from the path remainder. */
+function splitPrefix(uri) {
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]*\/?)/.exec(uri);
+    if (m)
+        return { prefix: m[1], rest: uri.slice(m[1].length) };
+    // A DRIVE is a root. Left as an ordinary segment it was one — so `..` could climb PAST `c:` and
+    // out of the volume, and `relativeUri` saw two different drives as sharing a root and produced a
+    // traversal between them. `c:/` is three characters, always.
+    if (DRIVE_ROOT.test(uri))
+        return { prefix: uri.slice(0, 3), rest: uri.slice(3) };
+    if (uri.startsWith('/'))
+        return { prefix: '/', rest: uri.slice(1) };
+    return { prefix: '', rest: uri };
+}
+function collapse(segments, keepLeadingDotDot) {
+    const out = [];
+    for (const seg of segments) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            const last = out[out.length - 1];
+            if (out.length > 0 && last !== '..') {
+                out.pop();
+            }
+            else if (keepLeadingDotDot) {
+                out.push('..');
+            }
+            // When traversal cannot be kept (rooted path), it is dropped —
+            // a rooted path can never escape its own root.
+            continue;
+        }
+        out.push(seg);
+    }
+    return out;
+}
+export function normalizeUri(uri) {
+    const forwardOnly = String(uri).replace(/\\/g, '/');
+    const { prefix, rest } = splitPrefix(forwardOnly);
+    const rooted = prefix !== '';
+    const segments = collapse(rest.split('/'), !rooted);
+    const joined = segments.join('/');
+    if (prefix === '')
+        return joined;
+    if (prefix === '/')
+        return `/${joined}`;
+    return joined === ''
+        ? prefix
+        : `${prefix.endsWith('/') ? prefix : `${prefix}/`}${joined}`;
+}
+export function joinUri(base, ...segments) {
+    const tail = segments.filter((s) => s !== undefined && s !== null && String(s) !== '');
+    const combined = [String(base), ...tail.map(String)].join('/');
+    return normalizeUri(combined);
+}
+export function dirnameUri(uri) {
+    const normalized = normalizeUri(uri);
+    const { prefix, rest } = splitPrefix(normalized);
+    const idx = rest.lastIndexOf('/');
+    if (idx === -1)
+        return prefix === '' ? '' : prefix;
+    return normalizeUri(`${prefix}${rest.slice(0, idx)}`);
+}
+export function basenameUri(uri) {
+    const normalized = normalizeUri(uri);
+    const { rest } = splitPrefix(normalized);
+    const idx = rest.lastIndexOf('/');
+    return idx === -1 ? rest : rest.slice(idx + 1);
+}
+/**
+ * True when `target` is absolute in its own right — rooted, drive-rooted, or schemed.
+ *
+ * Exported because `node:path`'s `isAbsolute` cannot answer this question for the web host: it
+ * knows nothing of `vscode-vfs://`, and on Windows it would reject a rooted POSIX path that is
+ * perfectly absolute in URI terms. This was the last of Story 1.5's 37 `path.*` call sites, and
+ * it had to move before `resolveMdIncludes` could follow the rest of the compose logic into core.
+ *
+ * ### The drive letter (reported 2026-08-08)
+ *
+ * It answered FALSE for `C:\docs\notes.md`, which is as absolute as a path gets. `merge.ts` asks
+ * this question at both `!md[…]` resolution sites — `isAbsoluteUri(ref) ? ref : resolveUri(base,
+ * ref)` — so an author on Windows writing an absolute include had it joined onto the project's base
+ * directory instead, producing `D:/project/C:/docs/notes.md` and an `ENOENT` naming a path nobody
+ * wrote. On Linux the same include starts with `/` and was always answered correctly, which is why
+ * only a Windows test run found it.
+ */
+export function isAbsoluteUri(target) {
+    const t = String(target).replace(/\\/g, '/');
+    return (t.startsWith('/') ||
+        /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(t) ||
+        DRIVE_ROOT.test(t));
+}
+export function resolveUri(base, target) {
+    return isAbsoluteUri(target) ? normalizeUri(target) : joinUri(base, target);
+}
+export function relativeUri(from, to) {
+    const a = normalizeUri(from);
+    const b = normalizeUri(to);
+    const pa = splitPrefix(a);
+    const pb = splitPrefix(b);
+    if (pa.prefix !== pb.prefix)
+        return b; // different roots — no relative path exists
+    const fromSeg = pa.rest.split('/').filter((s) => s !== '');
+    const toSeg = pb.rest.split('/').filter((s) => s !== '');
+    let i = 0;
+    while (i < fromSeg.length && i < toSeg.length && fromSeg[i] === toSeg[i])
+        i += 1;
+    const up = Array.from({ length: fromSeg.length - i }, () => '..');
+    return [...up, ...toSeg.slice(i)].join('/');
+}
+/**
+ * The escape guard (AC 5). True only when `child` is strictly inside `parent`.
+ *
+ * Segment-aware on purpose: a `startsWith` check would accept `rootsibling/x`
+ * for parent `root` and happily write outside the install target.
+ */
+export function isInsideUri(parent, child) {
+    const p = normalizeUri(parent);
+    const c = normalizeUri(child);
+    const pp = splitPrefix(p);
+    const pc = splitPrefix(c);
+    if (pp.prefix !== pc.prefix)
+        return false;
+    const pSeg = pp.rest.split('/').filter((s) => s !== '');
+    const cSeg = pc.rest.split('/').filter((s) => s !== '');
+    if (cSeg.length <= pSeg.length)
+        return false;
+    return pSeg.every((seg, i) => cSeg[i] === seg);
+}
+//# sourceMappingURL=uriPath.js.map

package/dist/uriPath.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beehexa/hexasync-template-model",
-  "version": "2608.20.18",
+  "version": "2608.20.31",
   "description": "Domain types for HexaSync templates. No behaviour.",
   "license": "SEE LICENSE IN ../../LICENSE",
   "type": "module",