aontu 0.52.1 → 0.54.0

package/dist/relation.js

@@ -0,0 +1,230 @@
+"use strict";
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relationFindings = relationFindings;
+exports.relationErrors = relationErrors;
+exports.relationCheck = relationCheck;
+// RELATION GRAPH VERDICTS (RELATIONS.0.md §3.3, replacing the G4
+// phase 5 magic-key pass): acyclicity and inverse consistency over
+// the edge set, DECLARED by the graph atoms -- `acyclic()` and
+// `inverse(name)` conjoined at the field whose key is the predicate
+// -- and decided AFTER unification, never by it.
+//
+// Why not in the lattice. Both properties are GLOBAL and NON-MONOTONE:
+// an acyclic graph becomes cyclic when one more edge unifies in, and an
+// inverse that is present becomes absent when the far side is narrowed.
+// The lattice guarantee is that more information never falsifies what
+// has been observed, so a constraint that could be true and then false
+// is not a constraint the lattice may hold. These are facts about the
+// finished model, so the atoms only REGISTER during unification
+// (GraphAtomVal.register, onto ctx._reldecls), and the verdict lands
+// at GENERATION -- the sizing atoms' model -- where no more
+// information can arrive. The `relations` verb reports the same
+// verdict from the same declarations: one decision, two surfaces.
+//
+// The old declaration channel -- a `relations:` key at the document
+// root, read by name -- is GONE, discharging ADR-010's grandfather
+// clause: the engine no longer knows any spellable key. The target
+// half of the old declaration is `rel(t)`'s flow at the site, which
+// checks by unifying rather than by a report-layer probe.
+const aontu_1 = require("./aontu");
+const vet_1 = require("./vet");
+const graph_1 = require("./graph");
+const keyorder_1 = require("./keyorder");
+const err_1 = require("./err");
+// The first cycle reachable from `start`, as the node paths it runs
+// through, or undefined. Depth-first with the path as the stack, and
+// the successors visited in sorted order, so the cycle a report names
+// is the same one in both ports.
+function findCycle(start, succ, done) {
+    const stack = [];
+    const onStack = new Set();
+    const walk = (node) => {
+        if (onStack.has(node)) {
+            return [...stack.slice(stack.indexOf(node)), node];
+        }
+        if (done.has(node)) {
+            return undefined;
+        }
+        done.add(node);
+        stack.push(node);
+        onStack.add(node);
+        for (const next of succ.get(node) ?? []) {
+            const found = walk(next);
+            if (undefined !== found) {
+                return found;
+            }
+        }
+        stack.pop();
+        onStack.delete(node);
+        return undefined;
+    };
+    return walk(start);
+}
+// The verdict itself, pure over what the evaluation produced: the
+// registered declarations and the edge set. Shared by the generation
+// hook (relationErrors) and the `relations` verb, so the two surfaces
+// cannot disagree.
+function relationFindings(decls, graph) {
+    const findings = [];
+    // The edge set, indexed the two ways the checks read it.
+    const byRelation = new Map();
+    const pairs = new Set();
+    for (const e of graph.edges) {
+        const list = byRelation.get(e.key);
+        if (undefined === list) {
+            byRelation.set(e.key, [e]);
+        }
+        else {
+            list.push(e);
+        }
+        pairs.add(e.key + ' ' + e.from + ' ' + e.to);
+    }
+    // Predicates in sorted order, so the findings arrive the same way
+    // in both ports (the registry is insertion-ordered here, random in
+    // Go).
+    const names = [...decls.keys()].sort(keyorder_1.cmpCodePoint);
+    for (const name of names) {
+        const decl = decls.get(name);
+        const mine = byRelation.get(name) ?? [];
+        if (true === decl.acyclic) {
+            const succ = new Map();
+            for (const e of mine) {
+                const list = succ.get(e.from);
+                const to = e.to;
+                if (undefined === list) {
+                    succ.set(e.from, [to]);
+                }
+                else {
+                    list.push(to);
+                }
+            }
+            for (const list of succ.values()) {
+                list.sort(keyorder_1.cmpCodePoint);
+            }
+            // The roots are visited in sorted order, and a node already
+            // settled is not revisited, so one cycle is reported once and the
+            // SAME one in both ports.
+            const done = new Set();
+            const roots = [...succ.keys()].sort(keyorder_1.cmpCodePoint);
+            for (const from of roots) {
+                const cycle = findCycle(from, succ, done);
+                if (undefined !== cycle) {
+                    // The cycle's first node is a key of `succ`, and every key of
+                    // `succ` came from an edge's `from`, so the edge is there.
+                    const at = mine.find((e) => e.from === cycle[0]);
+                    findings.push({
+                        code: 'relation_cycle',
+                        relation: name,
+                        at: at.at,
+                        detail: cycle,
+                    });
+                    break;
+                }
+            }
+        }
+        const inverses = [...decl.inverses].sort(keyorder_1.cmpCodePoint);
+        for (const inv of inverses) {
+            for (const e of mine) {
+                const to = e.to;
+                if (!pairs.has(inv + ' ' + to + ' ' + e.from)) {
+                    findings.push({
+                        code: 'relation_inverse_missing',
+                        relation: name,
+                        at: e.at,
+                        detail: [e.from, to, inv],
+                    });
+                }
+            }
+        }
+    }
+    // SORTED, because a report is read by a machine that diffs it: by the
+    // position the offending edge is written at, then by code, then by
+    // the detail (two inverse declarations on one predicate can flag one
+    // edge twice). The sort is STABLE and the predicates were iterated
+    // in sorted order, so what order remains is fixed anyway.
+    findings.sort((a, b) => (0, keyorder_1.cmpCodePoint)(a.at, b.at) || (0, keyorder_1.cmpCodePoint)(a.code, b.code)
+        || (0, keyorder_1.cmpCodePoint)(a.detail.join(' '), b.detail.join(' ')));
+    return findings;
+}
+// The generation hook (Aontu.generate, between unification success
+// and value generation): each finding becomes a LOCATED evaluation
+// error at the offending edge, exactly as an unmet sizing atom
+// refuses at generation. Findings name node paths and positions the
+// document spelled, so the walk to the site cannot miss.
+function relationErrors(ctx, root) {
+    const decls = ctx._reldecls;
+    if (0 === decls.size) {
+        return;
+    }
+    const findings = relationFindings(decls, (0, graph_1.graphOf)(root));
+    for (const f of findings) {
+        let node = root;
+        for (const seg of f.at.slice(2).split('.')) {
+            // Graph atoms hold the field's value -- possibly nested, one
+            // atom carrying another -- and the path steps through them
+            // exactly as the graph walk does.
+            while (true === node?.isGraphAtom) {
+                node = node.held;
+            }
+            node = node?.peg?.[seg];
+        }
+        // No unwrap AFTER the walk: a finding's `at` names an edge
+        // element, and an edge's element is a string -- an atom-wrapped
+        // element mints no edge in the first place (the graph visit
+        // descends atoms only at field values), so the walk cannot end on
+        // an atom.
+        ctx.adderr((0, err_1.makeNilErr)(ctx, f.code, node, undefined, 'relate', {
+            relation: f.relation,
+            detail: f.detail.join(' -> '),
+        }));
+    }
+}
+// The relation checks for one document: evaluate, then report the
+// same verdict generation enforces.
+function relationCheck(src, opts) {
+    const options = opts ?? {};
+    const aontu = new aontu_1.Aontu(null == options.trust ? undefined : { trust: options.trust });
+    const ctx = aontu.ctx({ collect: true });
+    const parseOpts = null == options.path ? undefined : { path: options.path };
+    const root = aontu.unify(src, parseOpts, ctx);
+    // A document that does not stand up is not a document with a bad
+    // graph: the errors it already has are the answer, and blaming its
+    // relations on top would be noise.
+    if (0 < ctx.err.length || true === root?.isNil) {
+        return {
+            verdict: 'error',
+            findings: [],
+            errors: [(0, vet_1.failureFinding)(ctx, options.path, root)],
+        };
+    }
+    const decls = ctx._reldecls;
+    if (0 === decls.size) {
+        return { verdict: 'pass', findings: [] };
+    }
+    // NOR IS A DOCUMENT THAT CANNOT BE GENERATED. Unification can
+    // succeed over a tree that still holds an unsettled disjunction --
+    // more than one alternative admitted, which `disjunct_no_gen`
+    // refuses at generation -- and the graph walk cannot read inside
+    // one: the links in every alternative are invisible, so a mirror
+    // the document plainly writes is missing from the edge set and
+    // `inverse(n)` calls it missing. Generation is therefore asked
+    // FIRST, on a collecting context of its own, and what it says is
+    // the answer. Generation is what the atoms' verdict lands at, so
+    // this is the same order the engine itself now runs in.
+    const gctx = ctx.clone({ err: [], collect: true });
+    root.gen(gctx);
+    if (0 < gctx.err.length) {
+        return {
+            verdict: 'error',
+            findings: [],
+            errors: [(0, vet_1.failureFinding)(gctx, options.path, root)],
+        };
+    }
+    const findings = relationFindings(decls, (0, graph_1.graphOf)(root));
+    return {
+        verdict: 0 === findings.length ? 'pass' : 'fail',
+        findings,
+    };
+}
+//# sourceMappingURL=relation.js.map

package/dist/relation.js.map

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

package/dist/report-sarif.d.ts

@@ -0,0 +1,14 @@
+import type { VetReport } from './vet';
+/**
+ * Render a vet report as SARIF 2.1.0 text (a minimal profile: one run,
+ * one result per finding, the finding embedded in `properties`).
+ *
+ * @param report   A report from `vet()`.
+ * @param version  The producer version for `tool.driver.version` —
+ *                 the CLI passes its package version; the two ports'
+ *                 version series are independent by design.
+ * @returns        The SARIF JSON text, indented two spaces, keys in
+ *                 the canonical emitter's sorted order.
+ */
+declare function sarifReport(report: VetReport, version: string): string;
+export { sarifReport, };

package/dist/report-sarif.js

@@ -0,0 +1,102 @@
+"use strict";
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sarifReport = sarifReport;
+const exactjson_1 = require("./exactjson");
+// SARIF levels are error/warning/note; the report's severities are
+// error/warning/info. Only `info` needs translating, but the map spells
+// out all three so a new severity fails loudly here rather than
+// silently emitting itself.
+const SARIF_LEVEL = {
+    error: 'error',
+    warning: 'warning',
+    info: 'note',
+};
+// A site's file is a filesystem path, and a SARIF artifactLocation.uri
+// is a URI reference: `#`, `%`, spaces and every other URI-significant
+// character must be percent-encoded or a consumer parses the path as
+// something else (text after `#` becomes a fragment). Encoded BY BYTE
+// over UTF-8, with RFC 3986's unreserved and path characters kept
+// literal, so the Go twin produces identical bytes from an identical
+// loop (go/report_sarif.go sarifURI).
+function sarifUri(path) {
+    const bytes = Buffer.from(path, 'utf8');
+    let out = '';
+    for (const b of bytes) {
+        const c = String.fromCharCode(b);
+        if (b < 128 && /[A-Za-z0-9\-._~/!$&'()*+,;=:@]/.test(c)) {
+            out += c;
+        }
+        else {
+            out += '%' + b.toString(16).toUpperCase().padStart(2, '0');
+        }
+    }
+    return out;
+}
+function sarifLocation(site) {
+    const physical = {
+        artifactLocation: { uri: sarifUri(site.file) },
+    };
+    // SARIF regions are 1-based. A finding with no position — a parse
+    // failure reports at -1:-1 — gets a location with no region rather
+    // than an invented one.
+    if (1 <= site.row) {
+        physical.region = { startColumn: site.col, startLine: site.row };
+    }
+    return { physicalLocation: physical };
+}
+function sarifResult(finding) {
+    // The engine orders sites data-first (the thing to fix), so the first
+    // site is the primary location and the rest are related — which for a
+    // two-site conflict puts the schema's declaration under
+    // `relatedLocations`, exactly where a code-scanning UI shows "the
+    // other side".
+    const result = {
+        level: SARIF_LEVEL[finding.severity],
+        locations: [sarifLocation(finding.sites[0])],
+        message: { text: finding.message },
+        properties: finding,
+        ruleId: 'aontu/' + finding.code,
+    };
+    const related = finding.sites.slice(1);
+    if (0 < related.length) {
+        result.relatedLocations = related.map(sarifLocation);
+    }
+    return result;
+}
+/**
+ * Render a vet report as SARIF 2.1.0 text (a minimal profile: one run,
+ * one result per finding, the finding embedded in `properties`).
+ *
+ * @param report   A report from `vet()`.
+ * @param version  The producer version for `tool.driver.version` —
+ *                 the CLI passes its package version; the two ports'
+ *                 version series are independent by design.
+ * @returns        The SARIF JSON text, indented two spaces, keys in
+ *                 the canonical emitter's sorted order.
+ */
+function sarifReport(report, version) {
+    return (0, exactjson_1.exactJSON)({
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        runs: [{
+                // An `error` verdict means the run could not be set up (an
+                // unusable schema): zero findings from a FAILED run must not
+                // read like zero findings from a clean one, so the failure is
+                // carried in SARIF's own invocation metadata rather than by an
+                // indistinguishable empty result list.
+                invocations: [{
+                        executionSuccessful: 'error' !== report.verdict,
+                    }],
+                results: report.findings.map(sarifResult),
+                tool: {
+                    driver: {
+                        informationUri: 'https://github.com/rjrodger/aontu',
+                        name: 'aontu',
+                        version,
+                    },
+                },
+            }],
+        version: '2.1.0',
+    }, 2);
+} /* node:coverage ignore next 6 */
+//# sourceMappingURL=report-sarif.js.map

package/dist/report-sarif.js.map

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

package/dist/sig.d.ts

@@ -0,0 +1,25 @@
+type ArgMode = 'value' | 'capture' | 'template' | 'trial' | 'projector' | 'text';
+type GroupSig = {
+    mode: ArgMode;
+    type: string;
+};
+type ArgSig = {
+    name: string;
+    mode: ArgMode;
+    type: string;
+    opt?: boolean;
+    rest?: boolean;
+    group?: GroupSig[];
+};
+type FuncSig = {
+    name: string;
+    args: ArgSig[];
+    out: string;
+};
+declare function parseSigLine(line: string): FuncSig;
+declare function renderSigArg(a: ArgSig): string;
+declare function renderSig(sig: FuncSig): string;
+declare function parseSigText(text: string): Record<string, FuncSig>;
+export type { ArgMode, ArgSig, GroupSig, FuncSig, };
+declare const funcSig: Record<string, FuncSig>;
+export { funcSig, parseSigLine, parseSigText, renderSig, renderSigArg, };

package/dist/sig.js

@@ -0,0 +1,277 @@
+"use strict";
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.funcSig = void 0;
+exports.parseSigLine = parseSigLine;
+exports.parseSigText = parseSigText;
+exports.renderSig = renderSig;
+exports.renderSigArg = renderSigArg;
+// THE SIGNATURE REGISTRY (docs/design/SIGNATURES.0.md). The call
+// surface of the built-in functions is DECLARED, in the signature
+// syntax itself, in test/spec/signature.tsv; this module is the
+// TypeScript half of the pair that reads it. The declaration text is
+// inlined at build time (ts/src/sigdecl.ts, `make sig`) and parsed at
+// initialisation by the signature grammar -- a custom tabnas grammar,
+// the same engine the aontu grammar itself is built on -- into the
+// registry the runtime signature checker, the error-message builder,
+// the docs table and the LSP all consume. Neither port authors a
+// table: go/sig.go parses the same text with the same grammar, and
+// the shared suite round-trips every line (render(parse(line)) is the
+// line) so the two parsers cannot drift.
+//
+//   line = name '(' [ arg {',' arg} ] ')' ':' type
+//   arg  = [mode] name ['?'] ':' type
+//        | '...' name ':' ( type | '(' [mode] type {',' [mode] type} ')' )
+//   type = word {'|' word}
+//   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'
+//
+// `value` mode is unmarked; the five marked modes are the vocabulary
+// plain pseudo-TypeScript cannot say (a captured spelling is not a
+// string value). The grammar is line-oriented: the loader strips
+// comment and blank lines and parses each declaration line alone, so
+// the grammar never sees line structure.
+const parser_1 = require("@tabnas/parser");
+const sigdecl_1 = require("./sigdecl");
+const ARG_MODES = {
+    capture: true, template: true, trial: true, projector: true, text: true,
+};
+// The signature grammar, as a tabnas grammar plugin. Rules: sig (the
+// line) -> args -> arg -> argtype -> type | group -> gmember. Alts
+// match at most two tokens, the engine's shape; lists loop the
+// json-grammar way (the element rule replaces itself on ',' and
+// backtracks the closer for its parent to consume).
+function sigGrammar(tn) {
+    tn.options({
+        fixed: {
+            token: {
+                '#OP': '(',
+                '#CP': ')',
+                '#QM': '?',
+                '#PI': '|',
+                '#DD': '...',
+            },
+        },
+        rule: { start: 'sig' },
+    });
+    // Parse-level validation errors, collected by the actions: the
+    // engine's own errors cover token shape, these cover word choice (a
+    // mode that is not a mode). Read after parse by parseSigLine.
+    const errs = [];
+    tn.sigErrs = errs;
+    const mode = (word) => {
+        if (true !== ARG_MODES[word]) {
+            errs.push('mode:' + word);
+            return 'value';
+        }
+        return word;
+    };
+    tn.grammar({
+        ref: {
+            '@sig-bo': (r) => {
+                r.node = { name: '', args: [], out: '' };
+                r.u.words = [];
+            },
+            '@signame': (r) => {
+                r.node.name = String(r.o0.val);
+            },
+            '@sigargs': (r) => {
+                r.node.args = r.child.node;
+            },
+            '@sigout': (r) => {
+                r.node.out = r.u.words.join('|');
+            },
+            '@args-bo': (r) => {
+                r.node = [];
+            },
+            '@arg-bo': (r) => {
+                r.u.sig = { name: '', mode: 'value', type: '' };
+            },
+            '@arg-rest': (r) => {
+                r.u.sig.rest = true;
+                r.u.sig.name = String(r.o1.val);
+            },
+            '@arg-modename': (r) => {
+                r.u.sig.mode = mode(String(r.o0.val));
+                r.u.sig.name = String(r.o1.val);
+            },
+            '@arg-name': (r) => {
+                r.u.sig.name = String(r.o0.val);
+            },
+            '@arg-opt': (r) => {
+                r.u.sig.opt = true;
+            },
+            '@arg-done': (r) => {
+                const sig = r.u.sig;
+                const at = r.child.node;
+                if (Array.isArray(at)) {
+                    sig.group = at;
+                    sig.type = '';
+                }
+                else {
+                    sig.type = String(at);
+                }
+                r.node.push(sig);
+            },
+            '@argtype-bo': (r) => {
+                r.u.words = [];
+            },
+            '@argtype-bc': (r) => {
+                r.node = 0 < r.u.words.length ?
+                    r.u.words.join('|') : r.child.node;
+            },
+            '@type-word': (r) => {
+                r.parent.u.words.push(String(r.o0.val));
+            },
+            '@group-bo': (r) => {
+                r.node = [];
+            },
+            '@gm-two': (r) => {
+                r.u.gm = { mode: mode(String(r.o0.val)), type: String(r.o1.val) };
+            },
+            '@gm-one': (r) => {
+                r.u.gm = { mode: 'value', type: String(r.o0.val) };
+            },
+            '@gm-done': (r) => {
+                r.node.push(r.u.gm);
+            },
+        },
+        rule: {
+            sig: {
+                open: [
+                    { s: '#TX #OP', a: '@signame', p: 'args' },
+                ],
+                close: [
+                    { s: '#CL', p: 'type', a: '@sigargs' },
+                    { s: '#ZZ', a: '@sigout' },
+                ],
+            },
+            args: {
+                open: [
+                    { s: '#CP', b: 1 },
+                    { p: 'arg' },
+                ],
+                close: [
+                    { s: '#CP' },
+                ],
+            },
+            arg: {
+                open: [
+                    { s: '#DD #TX', a: '@arg-rest' },
+                    { s: '#TX #TX', a: '@arg-modename' },
+                    { s: '#TX', a: '@arg-name' },
+                ],
+                close: [
+                    { s: '#QM #CL', a: '@arg-opt', p: 'argtype' },
+                    { s: '#CL', p: 'argtype' },
+                    { s: '#CA', a: '@arg-done', r: 'arg' },
+                    { s: '#CP', a: '@arg-done', b: 1 },
+                ],
+            },
+            argtype: {
+                open: [
+                    { s: '#OP', p: 'group' },
+                    { p: 'type' },
+                ],
+                close: [
+                    {},
+                ],
+            },
+            type: {
+                open: [
+                    { s: '#TX', a: '@type-word' },
+                ],
+                close: [
+                    { s: '#PI', r: 'type' },
+                    {},
+                ],
+            },
+            group: {
+                open: [
+                    { p: 'gmember' },
+                ],
+                close: [
+                    { s: '#CP' },
+                ],
+            },
+            gmember: {
+                open: [
+                    { s: '#TX #TX', a: '@gm-two' },
+                    { s: '#TX', a: '@gm-one' },
+                ],
+                close: [
+                    { s: '#CA', a: '@gm-done', r: 'gmember' },
+                    { s: '#CP', a: '@gm-done', b: 1 },
+                ],
+            },
+        },
+    });
+}
+let sigParser = undefined;
+function makeSigParser() {
+    if (undefined === sigParser) {
+        sigParser = new parser_1.Tabnas({ plugins: [sigGrammar] });
+    }
+    return sigParser;
+}
+// Parse ONE declaration line. A malformed line is an Error: the
+// declaration is repository content, read at build and test time, so
+// failing loudly is the right shape (the round-trip suite holds the
+// gate).
+function parseSigLine(line) {
+    const tn = makeSigParser();
+    tn.sigErrs.length = 0;
+    const out = tn.parse(line);
+    if (0 < tn.sigErrs.length) {
+        throw new Error('signature: bad declaration ' +
+            tn.sigErrs.join(',') + ': ' + line);
+    }
+    if (null == out || '' === out.name || '' === out.out) {
+        throw new Error('signature: incomplete declaration: ' + line);
+    }
+    return out;
+}
+// Render one argument of a signature -- the piece the LSP's
+// signatureHelp parameters share with the whole-line renderer.
+function renderSigArg(a) {
+    const type = undefined === a.group ? a.type :
+        '(' + a.group.map((g) => ('value' === g.mode ? '' : g.mode + ' ') + g.type).join(', ') + ')';
+    return (true === a.rest ? '...' : '') +
+        ('value' === a.mode || true === a.rest ? '' : a.mode + ' ') +
+        a.name +
+        (true === a.opt ? '?' : '') +
+        ': ' + type;
+}
+// Render the canonical line for a parsed signature -- the round-trip
+// twin of parseSigLine, and the one renderer every consumer (hints,
+// docs, LSP) uses.
+function renderSig(sig) {
+    return sig.name + '(' +
+        sig.args.map(renderSigArg).join(', ') + ') : ' + sig.out;
+}
+// Parse the whole declaration text: comment (#) and blank lines are
+// the loader's to skip, one FuncSig per remaining line, name-keyed.
+// A duplicate name is an error for the same reason a bad line is.
+function parseSigText(text) {
+    const reg = {};
+    for (const rawline of text.split('\n')) {
+        const line = rawline.trim();
+        if ('' === line || line.startsWith('#')) {
+            continue;
+        }
+        const sig = parseSigLine(line);
+        if (undefined !== reg[sig.name]) {
+            throw new Error('signature: duplicate declaration: ' + sig.name);
+        }
+        reg[sig.name] = sig;
+    }
+    return reg;
+}
+// The parsed registry, built once from the inlined declaration -- the
+// one source every consumer (the arity tables, the runtime gate, the
+// hints, the docs table, the LSP) reads. A parse failure here throws
+// at module load: the inlined text is repository content whose parse
+// the round-trip suite gates, so a failure is a build defect, not a
+// runtime condition. Twin: funcSig in go/sig.go.
+const funcSig = parseSigText(sigdecl_1.SIGDECL); /* node:coverage ignore next 9 */
+exports.funcSig = funcSig;
+//# sourceMappingURL=sig.js.map