hclang 0.15.1 → 0.17.0

package/esm/cli/hc.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import "../_dnt.polyfills.js";
 import * as dntShim from "../_dnt.shims.js";
+import { visibleEnvironment } from "../lib/execute/env-visibility.js";
 import { HCEval, make_context } from "../lib/execute/hc-eval.js";
 import { HCLog } from "../lib/execute/hc-log.js";
 import { HCTest } from "../lib/execute/hc-test.js";
@@ -8,7 +9,7 @@ import { parseArgs } from "../deps/jsr.io/@std/cli/1.0.32/parse_args.js";
 import { runfile } from "./runfile.js";
 import { Prompt } from "./prompt.js";
 import { DenoFileStore } from "./resource-store.js";
-import { Frame, FrameResource, RESOURCE_ROOT_KEY, } from "../lib/frames.js";
+import { CLOCK_SCHEME, ClockHandler, Frame, FrameResource, RealClock, RESOURCE_ROOT_KEY, ResourceHandlers, } from "../lib/frames.js";
 /**
  * @module hc
  *
@@ -71,9 +72,26 @@ export function getHost(context = {}) {
     // logger holds the same one: the root binding belongs to the host namespace
     // and nowhere else.
     const host = new Frame({ ...context });
-    host.set(RESOURCE_ROOT_KEY, FrameResource.root(new DenoFileStore()));
+    host.set(RESOURCE_ROOT_KEY, FrameResource.root(new DenoFileStore(), getHandlers()));
     return host;
 }
+/**
+ * This harness's scheme table.
+ *
+ * One entry, and the emptiness of every other slot is the point: `'https://…'`
+ * refuses because nothing is bound to `https`, not because a rule forbids it.
+ * The CLI installs the real clock, which is the only thing this harness can
+ * honestly implement that the root binding does not already cover.
+ *
+ * Exported so a test can run under the table the CLI actually grants.
+ *
+ * @returns The scheme handlers reachable from a CLI evaluation.
+ */
+export function getHandlers() {
+    return ResourceHandlers.of({
+        [CLOCK_SCHEME]: new ClockHandler(new RealClock()),
+    });
+}
 /**
  * The main function for the CLI application.
  *
@@ -147,7 +165,10 @@ export async function main(hcEval, options) {
     return lexicalComplete ? test?.exitCode ?? 0 : 1;
 }
 if (globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).main) {
-    const env = dntShim.Deno.env.toObject();
+    // One name at a time, through the dictionary. A wholesale read would hand the
+    // whole process environment to `$$` again, and the flags this harness runs
+    // under are a derived artifact rather than the bound.
+    const env = visibleEnvironment((name) => dntShim.Deno.env.get(name));
     const options = getOptions(dntShim.Deno.args);
     const hc_eval = getEval(env);
     main(hc_eval, options).then((exitCode) => {

package/esm/lib/execute/env-visibility.js

@@ -0,0 +1,80 @@
+/**
+ * Standard UNIX variables, which describe the invocation rather than the host's
+ * secrets. Every one of these is already visible to anything the user runs.
+ */
+const UNIX_VARIABLES = [
+    "HOME",
+    "HOSTNAME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "LOGNAME",
+    "PATH",
+    "PWD",
+    "SHELL",
+    "SHLVL",
+    "TMPDIR",
+    "TZ",
+    "USER",
+];
+/**
+ * Variables open-source tooling probes.
+ *
+ * This group is load-bearing rather than generous: the CLI's own dependency
+ * tree reads the colour-support family, and `DEBUG`/`DEBUG_ENV` are read by the
+ * logger and the context builder. Omitting them would leave a dictionary that
+ * looks tidy and breaks the harness that uses it.
+ *
+ * Deliberately absent: the CI-vendor names that same dependency reads to guess
+ * at colour support — `TF_BUILD`, `GITHUB_ACTIONS`, `TRAVIS`, and a dozen more.
+ * Which CI a build runs under is the harness's business, not a property of the
+ * invocation a program should describe itself with, and they reach the dependency
+ * through the flag rather than through this dictionary. The vendor-neutral `CI`
+ * stays, because that one is a fact about the invocation.
+ */
+const TOOLING_VARIABLES = [
+    "CI",
+    "COLORTERM",
+    "DEBUG",
+    "DEBUG_ENV",
+    "EDITOR",
+    "FORCE_COLOR",
+    "NO_COLOR",
+    "PAGER",
+    "TERM",
+    "TERM_PROGRAM",
+    "TERM_PROGRAM_VERSION",
+];
+/** The curated default dictionary, which a harness may replace wholesale. */
+export const VISIBLE_ENVIRONMENT = Object.freeze([
+    ...UNIX_VARIABLES,
+    ...TOOLING_VARIABLES,
+]);
+/**
+ * Reads only the declared variables, one name at a time.
+ *
+ * Never a wholesale read. Asking for the names the dictionary lists is what
+ * makes the dictionary the bound: a variable it omits is never read, so it
+ * cannot arrive by accident when the host grows a new one.
+ *
+ * A read the host refuses is absent for the same reason a read the dictionary
+ * omits is absent — the harness's own permission flags must not become
+ * something a program can detect.
+ */
+export const visibleEnvironment = (read, visible = VISIBLE_ENVIRONMENT) => {
+    const environment = {};
+    for (const name of visible) {
+        const value = readOrAbsent(read, name);
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    return environment;
+};
+const readOrAbsent = (read, name) => {
+    try {
+        return read(name);
+    }
+    catch {
+        return undefined;
+    }
+};

package/esm/lib/execute/syntax.js

@@ -32,6 +32,7 @@ export const syntaxFacets = [
     frame.FrameString.SYNTAX,
     frame.FrameStringEnd.SYNTAX,
     frame.FrameSymbol.SYNTAX,
+    frame.FrameTime.SYNTAX,
     frame.FrameURI.SYNTAX,
 ];
 const lexicalModes = {

package/esm/lib/frames/atom-syntax.js

@@ -9,6 +9,15 @@
  * @module
  */
 import { ScanDisposition } from "../scan.js";
+/**
+ * The delimiter that opens and closes a time literal.
+ *
+ * The time family owns it, but the operator family has to agree about it: `%` is
+ * an operator continuation character, so without a shared name an operator would
+ * swallow the sigil of a literal abutting it. It lives here, with the other
+ * facts both families read, rather than in either one of them.
+ */
+export const TIME_DELIMITER = "%";
 /** Counts non-overlapping occurrences of `token` in `source`. */
 const occurrences = (source, token) => source.split(token).length - 1;
 /** Consume an accepted character; otherwise end the atom before it. */

package/esm/lib/frames/clock.js

@@ -0,0 +1,177 @@
+/**
+ * The clock, as a handler table entry.
+ *
+ * A time literal is inert data; reading the current instant is not. `now` reads
+ * something outside the program, so it cannot be ambient — there is no nameable
+ * primitive for it and therefore no way for a program to request one. The clock
+ * is a harness grant like any other resource, spelled `'clock:now'`, and a
+ * harness that installs no clock leaves the scheme an empty slot.
+ *
+ * Real, frozen, and scripted clocks are three entries, not three modes. The
+ * program is byte-identical across all of them, exactly as it is across any other
+ * handler swap, which is what finally lets a `;` source and `#` expected pair say
+ * something time-dependent.
+ *
+ * What holds for a program that is refused: no reading is available, whether the
+ * scheme was never bound or the clock declined, and either way the refusal is an
+ * ordinary value that flows back through evaluation rather than raising. It does
+ * *not* hold that the two are indistinguishable — `$!.resource-scheme-unbound`
+ * and `$!.clock-exhausted` are different values, and a program can read them.
+ * That is deliberate here and general to the resource primitive, whose refusals
+ * are nameable by design; `spec/a12-resource-frames.md` records the tension with
+ * a07 §7's stronger claim rather than resolving it in this one handler.
+ *
+ * @module
+ */
+import { FrameDateTime } from "./frame-time.js";
+/** The scheme a harness binds a clock to. */
+export const CLOCK_SCHEME = "clock";
+/** The one reading a clock answers to. */
+const NOW = "now";
+/** The host clock, which prod installs and nothing else should. */
+export class RealClock {
+    describe() {
+        return "real";
+    }
+    now() {
+        return { ok: true, instant: FrameDateTime.fromEpochMillis(Date.now()) };
+    }
+}
+/**
+ * One instant, answered every time.
+ *
+ * This is what retires the deterministic-build-timestamp workaround: a
+ * reproducible build pins the clock instead of deriving a substitute for one.
+ */
+export class FrozenClock {
+    constructor(instant) {
+        Object.defineProperty(this, "instant", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: instant
+        });
+    }
+    describe() {
+        return `frozen ${this.instant.canonical()}`;
+    }
+    now() {
+        return { ok: true, instant: this.instant };
+    }
+}
+/**
+ * A finite script of instants, which refuses once spent.
+ *
+ * Exhaustion is the clock refusing, which is the general shape a time budget
+ * takes: a limit on time is a duration plus a clock, not a limiter subsystem.
+ */
+export class ScriptedClock {
+    constructor(readings) {
+        Object.defineProperty(this, "readings", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: readings
+        });
+        Object.defineProperty(this, "next", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+    }
+    describe() {
+        return `scripted ${this.readings.length}`;
+    }
+    now() {
+        const reading = this.readings[this.next];
+        if (reading === undefined) {
+            return { ok: false, reason: "clock-exhausted" };
+        }
+        this.next += 1;
+        return { ok: true, instant: reading };
+    }
+}
+/**
+ * A clock that stops once a duration has elapsed.
+ *
+ * The budget is a duration value and the exhaustion is the clock refusing, so
+ * nothing here is a scheduler: the first reading starts the budget and a reading
+ * past it is `clock-budget-spent`.
+ */
+export class BudgetClock {
+    constructor(clock, budget) {
+        Object.defineProperty(this, "clock", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: clock
+        });
+        Object.defineProperty(this, "budget", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: budget
+        });
+        Object.defineProperty(this, "started", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+    }
+    describe() {
+        return `budget ${this.budget.canonical()} on ${this.clock.describe()}`;
+    }
+    now() {
+        const reading = this.clock.now();
+        if (!reading.ok)
+            return reading;
+        this.started ??= reading.instant.nanos;
+        return reading.instant.nanos - this.started > this.budget.nanos
+            ? { ok: false, reason: "clock-budget-spent" }
+            : reading;
+    }
+}
+/**
+ * Binds a clock to the `clock` scheme.
+ *
+ * Reading answers the instant itself rather than its characters, because the
+ * handler already knows the value and spelling it as text would only make every
+ * reader parse it back. Writing is refused: a clock is an observation, and a
+ * program that could set one could make its own history.
+ */
+export class ClockHandler {
+    constructor(clock) {
+        Object.defineProperty(this, "clock", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: clock
+        });
+    }
+    describe() {
+        return `${CLOCK_SCHEME}:${this.clock.describe()}`;
+    }
+    read(reference) {
+        if (!ClockHandler.readsNow(reference)) {
+            return { ok: false, reason: "clock-unreadable" };
+        }
+        const reading = this.clock.now();
+        return reading.ok
+            ? { ok: true, elements: [reading.instant] }
+            : { ok: false, reason: reading.reason };
+    }
+    write(_reference, _content) {
+        return { ok: false, reason: "clock-read-only" };
+    }
+    /** `'clock:now'` is the whole vocabulary; anything else names nothing. */
+    static readsNow(reference) {
+        if (reference.authority !== undefined)
+            return false;
+        if (reference.query !== undefined || reference.fragment !== undefined) {
+            return false;
+        }
+        return (reference.path ?? "").replace(/^\/+/, "") === NOW;
+    }
+}

package/esm/lib/frames/dimensional-algebra.js

@@ -0,0 +1,43 @@
+/**
+ * Which operand kinds combine, and what they answer.
+ *
+ * Datetime and duration are a two-element instance of the general dimensional
+ * rule, not a special case of time: an instant is a point on a line, a duration
+ * is an interval on it, and the algebra that relates them is the affine one.
+ * Writing it as a table rather than as branches inside a frame class is what
+ * keeps the units work from becoming a parallel implementation of the same
+ * rules — a dimensioned quantity is an interval on its own line, and a plain
+ * number is the scalar.
+ *
+ * The table is the whole ruling. A combination it does not name has no meaning,
+ * so the caller answers a type error rather than inventing one, which is how
+ * `datetime + datetime` becomes an error frame instead of a second datetime.
+ *
+ * @module
+ */
+/**
+ * Every combination that means something, keyed by operator and operand kinds.
+ *
+ * Read the omissions as deliberately as the entries: `+ point point` has no
+ * meaning because adding two positions depends on an origin the values do not
+ * carry, and `- interval point` is refused because subtraction is not
+ * commutative and a displacement minus a position is not a position.
+ */
+const RESULTS = Object.freeze({
+    "+ point interval": "point",
+    "+ interval point": "point",
+    "+ interval interval": "interval",
+    "+ scalar scalar": "scalar",
+    "- point point": "interval",
+    "- point interval": "point",
+    "- interval interval": "interval",
+    "- scalar scalar": "scalar",
+    "* interval scalar": "interval",
+    "* scalar interval": "interval",
+    "* scalar scalar": "scalar",
+    "/ interval scalar": "interval",
+    "/ interval interval": "scalar",
+    "/ scalar scalar": "scalar",
+});
+/** The kind this combination answers, or undefined when it has no meaning. */
+export const dimensionalResult = (operator, left, right) => RESULTS[`${operator} ${left} ${right}`];

package/esm/lib/frames/evaluation-scope.js

@@ -166,15 +166,16 @@ export class EvaluationScope {
      * the argument to the argument", which is what made a closure's write target
      * and its argument the same frame and produced a self-referential binding.
      *
-     * A handle argument is the one exception, because a handle is explicitly a
-     * mutable view requested by the caller for exactly this purpose.
+     * A mutable handle argument is the one exception, because the caller asked
+     * for a mutable view by spelling the name with the effect marker (`x_`). A
+     * plain name also arrives as a handle, but an immutable one, and it grants no
+     * write: `f x` must not change `x`.
      */
     static call(argument, parameter = Frame.nil, closure, enclosing, receiverState) {
         const local = new Frame();
-        const target = argument instanceof FrameHandle ? argument.unwrap() : local;
-        const targetRole = argument instanceof FrameHandle
-            ? "handle"
-            : "statement";
+        const writable = argument instanceof FrameHandle && argument.isMutable();
+        const target = writable ? argument.unwrap() : local;
+        const targetRole = writable ? "handle" : "statement";
         const lookupFrames = [local, argument];
         if (!parameter.is.void)
             lookupFrames.push(parameter);

package/esm/lib/frames/frame-array.js

@@ -1,3 +1,4 @@
+import { Frame } from "./frame.js";
 import { FrameExpr } from "./frame-expr.js";
 import { FrameList } from "./frame-list.js";
 import { FrameNote } from "./frame-note.js";
@@ -51,6 +52,58 @@ export class FrameArray extends FrameList {
         }
         return undefined;
     }
+    /** Aggregates own identity, so `===` compares them by reference. */
+    ownsIdentity() {
+        return true;
+    }
+    /**
+     * `=` compares the complete view, the same one `&&` iterates: visible
+     * properties in declaration order, then elements by index, each by `=`.
+     * Spelling, private fields, the declared parent, and ids are not the value.
+     */
+    equals(other) {
+        return this.sameMembers(other, (left, right) => left.equals(right));
+    }
+    /** `==` is the same walk with `==` at every node. */
+    typeEquals(other) {
+        return this.sameMembers(other, (left, right) => left.typeEquals(right));
+    }
+    sameMembers(other, same) {
+        const right = other.referent();
+        if (right === this)
+            return Frame.all;
+        if (right.constructor !== this.constructor)
+            return Frame.nil;
+        const inProgress = FrameArray.comparing.get(this) ?? new Set();
+        if (inProgress.has(right))
+            return Frame.all;
+        inProgress.add(right);
+        FrameArray.comparing.set(this, inProgress);
+        try {
+            const keys = this.visibleKeys();
+            const rightKeys = right.visibleKeys();
+            if (keys.length !== rightKeys.length ||
+                keys.some((key, index) => key !== rightKeys[index]))
+                return Frame.nil;
+            for (const key of keys) {
+                if (same(this.get_here(key), right.get_here(key)) !== Frame.all) {
+                    return Frame.nil;
+                }
+            }
+            const elements = this.elements();
+            const rightElements = right.elements();
+            if (elements.length !== rightElements.length)
+                return Frame.nil;
+            return elements.every((element, index) => same(element, rightElements[index]) === Frame.all)
+                ? Frame.all
+                : Frame.nil;
+        }
+        finally {
+            inProgress.delete(right);
+            if (inProgress.size === 0)
+                FrameArray.comparing.delete(this);
+        }
+    }
     /**
      * Aggregates are where identity matters, so an instance copy isolates them:
      * every nested aggregate, in the data plane and the metadata plane alike, gets
@@ -127,3 +180,10 @@ Object.defineProperty(FrameArray, "SIGIL_STARTS", {
         { key: FrameArray.END_ARRAY, mode: "pop" },
     ]
 });
+/** Pairs under comparison, so a frame reachable from itself terminates. */
+Object.defineProperty(FrameArray, "comparing", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Map()
+});

package/esm/lib/frames/frame-handle.js

@@ -60,6 +60,20 @@ export class FrameHandle extends Frame {
     unwrap() {
         return this.target;
     }
+    /** A handle is transparent to equality: it compares as its target. */
+    referent() {
+        return this.target.referent();
+    }
+    equals(other) {
+        return this.target.equals(other);
+    }
+    typeEquals(other) {
+        return this.target.typeEquals(other);
+    }
+    /** Whether the name that produced this handle carried the effect marker. */
+    isMutable() {
+        return this.mutable;
+    }
     /** The lexical fallback selected for this particular read. */
     readContextFrame() {
         return this.readContext;

package/esm/lib/frames/frame-numeric.js

@@ -78,7 +78,7 @@ export class FrameNumeric extends FrameAtom {
     }
     divide(right) {
         if (this.rank == null || right.rank == null) {
-            return this.operationError("/", right);
+            return this.reflect("/", right) ?? this.operationError("/", right);
         }
         if (right.isZero())
             return Frame.error("$!.division-by-zero /");
@@ -171,6 +171,17 @@ export class FrameNumeric extends FrameAtom {
     exactInt(_max) {
         return Frame.error(`$!.exact-integer-required ${this.className()}`);
     }
+    /**
+     * The exact ratio this frame denotes, or null when it denotes none.
+     *
+     * Published so a null-ranked peer outside the promotion ladder can scale by an
+     * exact scalar without joining the ladder to do it. An inexact value answers
+     * null, which is what keeps such a peer's arithmetic exact by construction
+     * rather than by rounding.
+     */
+    exactRatio() {
+        return this.ratioParts();
+    }
     operationError(operator, right) {
         return Frame.error(`$!.numeric-domain ${operator} ${this.className()} ${right.className()}`);
     }
@@ -180,6 +191,17 @@ export class FrameNumeric extends FrameAtom {
     repeat(_argument, _parameter) {
         return this.repetitionError();
     }
+    /**
+     * A right operand's chance to define an operation its left cannot.
+     *
+     * A value outside the promotion ladder carries rules the ladder does not know:
+     * a duration times a number is a duration, whichever side the number was
+     * written on. Answering `undefined` — which every ranked type does — leaves the
+     * domain error exactly as it was, so this adds a case rather than changing one.
+     */
+    combineFrom(_operator, _left) {
+        return undefined;
+    }
     /**
      * A numeric `up` link is the receiver a property lookup climbed from, not a
      * lexical scope, so it must not answer a later segment. Without this, an
@@ -201,11 +223,18 @@ export class FrameNumeric extends FrameAtom {
     }
     join(right, operator, operation) {
         if (this.rank == null || right.rank == null) {
-            return this.operationError(operator, right);
+            return this.reflect(operator, right) ??
+                this.operationError(operator, right);
         }
         const target = Math.max(this.rank, right.rank);
         return operation(this.promoteTo(target), right.promoteTo(target));
     }
+    /** Offers an unranked right operand the operation, once, before refusing. */
+    reflect(operator, right) {
+        return this.rank != null && right.rank == null
+            ? right.combineFrom(operator, this)
+            : undefined;
+    }
     order(right, operator, predicate) {
         if (this.rank == null || right.rank == null) {
             return this.operationError(operator, right);