parseman 0.45.0 → 0.46.0

package/dist/analysis/fix-render.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The human layer over `FixReport`.
+ *
+ * The claim this rendering has to carry is unusual, so it is made explicitly and never
+ * by implication: a fix shown here was APPLIED to the grammar, the grammar was
+ * RECOMPILED, the corpus was RE-PARSED, and the output did not move. Every offered
+ * rewrite prints that evidence next to it, with the sample and byte counts, because
+ * "proven" without a corpus size is a word, not a fact.
+ *
+ * The diff is the primary interface. `--apply` writing to a file is a second, explicit
+ * step; what a reader gets by default is what would change, in the form they would read
+ * it in a review.
+ *
+ * TWO STATES, MADE VISUALLY DISTINCT
+ * ----------------------------------
+ * ACTIONABLE and LOCATED are the whole model, and in the first cut they were two words
+ * in the same colour — which is to say, not a distinction at all until you read them.
+ * They now differ in glyph, colour and weight, so a reader triages the report by
+ * scanning the left margin rather than by parsing it. LOCATED prints the REASON and
+ * never advice: a site that cannot be rewritten is still worth knowing about, and that
+ * is the difference between "here is exactly where the problem is" and silence.
+ *
+ * Like `diagnose-render.ts`, this emits LINES OF SPANS and never an escape byte;
+ * `terminal.ts` owns every interaction with a terminal.
+ */
+import type { FixReport } from './fix.ts';
+import { type Line, type RenderTarget } from './terminal.ts';
+export type FixRenderOptions = RenderTarget & {
+    name?: string;
+    /**
+     * How many edits were WRITTEN to disk. A count, not a flag: `applyFixEdits` skips an
+     * edit whose span moved under it, so a run can write some of `r.verified` and skip the
+     * rest. A boolean here made the report say every verified change had been written
+     * whenever any one of them had been — the one number a reader checks after `--apply`,
+     * wrong in exactly the case that matters. Absent (or 0) means nothing was written.
+     */
+    applied?: number;
+    /** Absolute path of the edited source, used ONLY for the frame's terminal hyperlink. */
+    sourceRoot?: string;
+};
+export declare function fixReportLines(r: FixReport, opts?: FixRenderOptions): Line[];
+export declare function renderFixReport(r: FixReport, opts?: FixRenderOptions): string;
+//# sourceMappingURL=fix-render.d.ts.map

package/dist/analysis/fix-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-render.d.ts","sourceRoot":"","sources":["../../src/analysis/fix-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,SAAS,EAA+B,MAAM,UAAU,CAAA;AACtE,OAAO,EAEL,KAAK,IAAI,EAAE,KAAK,YAAY,EAC7B,MAAM,eAAe,CAAA;AAEtB,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,GAAE,gBAAqB,GAAG,IAAI,EAAE,CA6EhF;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAEjF"}

package/dist/analysis/fix.d.ts

@@ -0,0 +1,172 @@
+/**
+ * VERIFIED grammar fixes — the propose → apply → recompile → compare loop.
+ *
+ * rustc can tell you a suggestion is machine-applicable. It cannot tell you the
+ * suggestion is CORRECT: there is no cheap oracle for "this rewrite of your program
+ * means the same thing". A parser generator has one. A grammar's whole observable
+ * behaviour is the tree it produces for an input, so a rewrite can be applied, the
+ * grammar recompiled, a corpus re-parsed, and the two outputs compared byte for byte.
+ * Unchanged output is not a heuristic that the rewrite was safe; it is the evidence.
+ *
+ *     propose  →  apply  →  recompile  →  compare parse output
+ *                                          unchanged → PROVEN over this corpus; offer it
+ *                                          changed   → WRONG; discard, never show it
+ *
+ * TWO STATES, NEVER A THIRD
+ * -------------------------
+ * Every candidate site ends as ACTIONABLE (here is the rewrite, here is the evidence,
+ * here is the measured benefit) or LOCATED (here is the exact site and the exact reason
+ * no rewrite can be offered). There is no "consider refactoring": a sentence of advice
+ * with no location and no rewrite is the thing this module exists to replace. A rewrite
+ * that moved the output is reported as LOCATED with the rejection as its reason — the
+ * site is real, the rewrite is not shown, and the reader is never handed a wrong fix.
+ *
+ * WHAT "PROVEN" MEANS HERE, EXACTLY
+ * ---------------------------------
+ * Proven OVER THE SUPPLIED CORPUS, on every engine the grammar supports — both when it
+ * compiles, the interpreted one alone when it does not — and that is stated in every
+ * rendering rather than implied. A corpus that never reaches the rewritten arm proves
+ * nothing about it, so the evidence carries the sample and byte counts and the caller
+ * can judge. Two deliberate exclusions from the comparison:
+ *
+ *   - FAILURE `expected` LABELS are compared as position only, not text. A keyword
+ *     rewrite changes `/\@media/` to `keyword` by design; that is diagnostic text, not
+ *     parse output. Values, spans, and WHERE a parse failed are compared exactly.
+ *   - The rebuild itself is not trusted, it is CHECKED: before any candidate is
+ *     considered, the grammar is rebuilt with NO substitution and that identity rebuild
+ *     must reproduce the corpus output exactly. If `rebuild.ts` threads any option
+ *     wrongly, this check fails and NO fix is offered. Wrong makes the tool silent.
+ *
+ * BENEFIT IS MEASURED TOO
+ * -----------------------
+ * A verified-but-pointless rewrite is not offered either. Benefit is read off the same
+ * analysis a CI gate reads — ungated choices, anti-patterns — plus the compiled artifact
+ * size, which is deterministic and therefore safe to print. No timings: this must be
+ * diffable.
+ */
+import type { Combinator } from '../types.ts';
+import { type FrozenSubtree } from './rebuild.ts';
+/** One corpus document. `name` is a label for the report; it is never a path lookup. */
+export type FixSample = {
+    name: string;
+    text: string;
+};
+/** Stable, greppable fix class. Mirrors the `anti-pattern` kinds `diagnoseGrammar` reports. */
+export type FixCode = 'keyword-regex' | 'double-not';
+/** The engines a comparison ran on. `compiled` is absent when the grammar does not compile. */
+export type FixEngine = 'interpreted' | 'compiled';
+export type FixEvidence = {
+    samples: number;
+    bytes: number;
+    engines: FixEngine[];
+    /** Always true on a VERIFIED fix — the field exists so the JSON states the claim. */
+    outputUnchanged: true;
+};
+export type FixBenefit = {
+    ungatedChoicesBefore: number;
+    ungatedChoicesAfter: number;
+    antiPatternsBefore: number;
+    antiPatternsAfter: number;
+    gatedChoicesBefore: number;
+    gatedChoicesAfter: number;
+    /** Bytes of `compile().source`. Deterministic. `null` when the grammar does not compile. */
+    codegenBytesBefore: number | null;
+    codegenBytesAfter: number | null;
+};
+/** A source edit, offered only when the site is UNAMBIGUOUS in the supplied text. */
+export type FixEdit = {
+    path: string;
+    /** 1-based, for a diagnostic header. */
+    line: number;
+    column: number;
+    start: number;
+    end: number;
+    oldText: string;
+    newText: string;
+    /** The whole source line the edit sits on, so a renderer can draw a real code frame. */
+    lineText: string;
+};
+export type VerifiedFix = {
+    id: string;
+    code: FixCode;
+    rule: string;
+    armIndex: number;
+    /** How the site reads now, and how it would read. Rendering, not source text. */
+    before: string;
+    after: string;
+    /** The arm's deep first-set before and after — the number that makes the fix self-evident. */
+    armFirstSetBefore: string;
+    armFirstSetAfter: string;
+    /** The enclosing choice's gating verdict, before and after. */
+    choiceId: string;
+    choiceGatesBefore: 'yes' | 'recoverable' | 'no';
+    choiceGatesAfter: 'yes' | 'recoverable' | 'no';
+    benefit: FixBenefit;
+    evidence: FixEvidence;
+    /** Present only when the site was located unambiguously in a supplied source file. */
+    edit?: FixEdit;
+};
+export type LocatedFinding = {
+    id: string;
+    code: FixCode;
+    rule: string;
+    armIndex: number;
+    /** How the site reads now. */
+    site: string;
+    /** The exact reason no rewrite can be offered. Never advice. */
+    reason: string;
+};
+export type FixReport = {
+    schema: 'parseman.fix/1';
+    /**
+     * True when every candidate site got a verdict — i.e. the corpus was usable and the
+     * identity rebuild held. FALSE IS NOT "no fixes": it means the loop could not run, and
+     * an empty `verified` list under it proves nothing. Fails closed.
+     */
+    ok: boolean;
+    /** Why `ok` is false, or `null`. */
+    blocked: string | null;
+    corpus: {
+        samples: number;
+        bytes: number;
+    };
+    engines: FixEngine[];
+    verified: VerifiedFix[];
+    located: LocatedFinding[];
+    /** Subtrees `rebuild.ts` reused verbatim; a candidate inside one cannot be applied. */
+    frozen: FrozenSubtree[];
+};
+export type ProposeFixOptions = {
+    /**
+     * The documents the before/after comparison runs over. REQUIRED and non-empty: with no
+     * corpus there is no evidence, and this module does not offer unverified rewrites.
+     */
+    corpus: readonly FixSample[];
+    /** Grammar source, to locate edits in. Without it, fixes carry no `edit`. */
+    source?: {
+        path: string;
+        text: string;
+    };
+    /** Passed through to `analyzeGating` when measuring benefit. */
+    accept?: Iterable<string>;
+    entryName?: string;
+};
+/**
+ * Propose fixes, and offer only the ones proven output-neutral over `opts.corpus`.
+ *
+ * Never throws: a loop that cannot run reports `ok: false` with the reason, because a
+ * thrown proposal and a grammar with nothing to fix must not look the same.
+ */
+export declare function proposeFixes(root: Combinator<unknown>, opts: ProposeFixOptions): FixReport;
+/**
+ * Apply verified edits to a source text, right-to-left so earlier offsets stay valid.
+ *
+ * Pure: it returns the new text and never touches the filesystem. Writing is the
+ * caller's explicit second step, which is what keeps `--apply` from being something that
+ * happens to you.
+ */
+export declare function applyFixEdits(sourceText: string, fixes: readonly VerifiedFix[]): {
+    text: string;
+    applied: number;
+};
+//# sourceMappingURL=fix.d.ts.map

package/dist/analysis/fix.d.ts.map

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

package/dist/analysis/gating.d.ts

@@ -109,6 +109,12 @@ export type ChoiceGating = {
     anyArms: AnyArm[];
     overlaps: Overlap[];
 };
+/**
+ * The arms a `ChoiceGating` describes, in arm order — or `undefined` when the report did
+ * not come from a live walk (a deserialized snapshot). Carried non-enumerably, so it
+ * never reaches the JSON a CI snapshot diffs.
+ */
+export declare const choiceArms: (c: ChoiceGating) => readonly Combinator<unknown>[] | undefined;
 /** Options for `analyzeGating` — the accepted-snapshot allowlist. */
 export type AnalyzeGatingOptions = {
     /**
@@ -181,6 +187,8 @@ export type GatingReport = {
     antiPatterns: AntiPattern[];
 };
 export declare function firstSetToString(fs: FirstSet): string;
+/** Peel non-consuming wrappers to the arm's leading term (mirrors leadingTermOfArm). */
+export declare function peelToLeading(arm: Combinator<unknown>): Combinator<unknown>;
 export declare function analyzeGating(entry: Combinator<unknown>, opts?: AnalyzeGatingOptions): GatingReport;
 /**
  * Multi-root variant: analyze a WHOLE `rules()` map in one walk, so every choice

package/dist/analysis/gating.d.ts.map

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

package/dist/analysis/rebuild.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Rebuild a combinator graph THROUGH THE PUBLIC FACTORIES, substituting selected nodes.
+ *
+ * This exists so a proposed grammar fix can be APPLIED and then MEASURED, rather than
+ * printed and hoped for. Everything downstream — `proposeFixes()` — depends on one
+ * property: a rewritten grammar must be a real grammar, built the same way the author's
+ * was, so that compiling it and parsing with it means the same thing.
+ *
+ * WHY THE FACTORIES AND NOT A `_def` DEEP-COPY
+ * --------------------------------------------
+ * A combinator is two things at once: a `_def` descriptor the COMPILER reads, and a
+ * `parse` closure the INTERPRETER runs, which captured its children when the factory
+ * ran. Patching `_def.parser` moves the compiled engine and leaves the interpreted one
+ * on the old graph — the two engines would then disagree, and a verification that runs
+ * either one would certify a rewrite that does not exist in the other. Re-running the
+ * factory produces both halves from the same inputs, and also recomputes everything
+ * DERIVED that the fix is trying to move in the first place: `_meta.firstSet`,
+ * `choice._def.disjoint`, and the choice strategy.
+ *
+ * FROZEN SUBTREES, NOT A FAILED REBUILD
+ * -------------------------------------
+ * Some node kinds have no faithful public reconstruction — `dispatch` (its arms carry
+ * matcher objects), `recover`, `scanTo`, `guard`, `withCtx`, `trivia` (classified
+ * trivia carries labels derived at construction). Refusing to rebuild a whole grammar
+ * because it contains one of them would make this useless on every real grammar. So
+ * such a node is REUSED VERBATIM: nothing inside it changed, so reusing it is exact.
+ * The cost is precise and reported — a rewrite target that sits inside a frozen subtree
+ * cannot be applied, and comes back in `unapplied` so the caller can say WHY rather
+ * than silently dropping it.
+ *
+ * THE HONESTY BACKSTOP
+ * --------------------
+ * This module does not claim to be faithful; it is CHECKED. `proposeFixes()` first
+ * rebuilds with NO substitutions and requires that identity rebuild to produce
+ * byte-identical parse output over the caller's corpus. If any option threading below
+ * is wrong, that check fails and NO fix is offered for that grammar. A rebuilder that
+ * is wrong makes the tool silent, never wrong.
+ */
+import type { Combinator } from '../types.ts';
+/** A subtree that was reused verbatim instead of rebuilt. */
+export type FrozenSubtree = {
+    tag: string;
+    /** Nearest enclosing rule name, so the report can point at it. */
+    rule: string;
+};
+export type RebuildResult = {
+    root: Combinator<unknown>;
+    /** Reused-verbatim subtrees, deduplicated by (rule, tag) and sorted. */
+    frozen: FrozenSubtree[];
+    /**
+     * Substitutions that could NOT be applied because their target sits inside a frozen
+     * subtree. Non-empty means the returned graph is NOT the graph the caller asked for.
+     */
+    unapplied: Combinator<unknown>[];
+};
+/**
+ * Rebuild `root`, replacing every combinator that is a key of `replacements` with its
+ * value. The replacement is spliced WITHOUT descending into the original target.
+ */
+export declare function rebuildCombinator(root: Combinator<unknown>, replacements: ReadonlyMap<Combinator<unknown>, Combinator<unknown>>): RebuildResult;
+//# sourceMappingURL=rebuild.d.ts.map

package/dist/analysis/rebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild.d.ts","sourceRoot":"","sources":["../../src/analysis/rebuild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,aAAa,CAAA;AAsBxD,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IACzB,wEAAwE;IACxE,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB;;;OAGG;IACH,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAA;CACjC,CAAA;AA0CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,EACzB,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,GAClE,aAAa,CA2Jf"}

package/dist/analysis/terminal.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The ONLY module in parseman that talks to a terminal.
+ *
+ * Everything above it produces DATA — lines made of spans, each span carrying text and a
+ * semantic tone — and this file turns lines into bytes. That split is not tidiness; it is
+ * what makes the rendering diffable. A renderer that emits escape sequences inline has
+ * two outputs (styled and plain) that can drift apart, and the plain one is what a
+ * snapshot, a CI log and `docs/samples/` all read.
+ *
+ * WHY LINECRAFT AND NOT HAND-ROLLED ANSI
+ * --------------------------------------
+ * The first cut of this CLI carried its own `ANSI` constant table. Writing that file
+ * silently dropped the ESC bytes, so colour was dead for an entire session and nothing
+ * said so — the output still looked structured, because an escape-less `[2m` prints as
+ * `[2m`. Escape sequences are invisible failure surface, and a library that owns them
+ * removes the surface. jess already renders its diagnostics through linecraft
+ * (`packages/compiler/src/diagnostics.ts`, `packages/lint/src/index.ts`), so following
+ * the same idiom also means a jess user and a parseman user see the same shape of output
+ * rather than two parallel inventions. Pinned to `0.2.6`, exactly matching jess's pins.
+ *
+ * SPANS, NOT WHOLE-LINE STYLES
+ * ----------------------------
+ * jess's lint table styles a whole row at a time, which is right for a table of one
+ * thing per line. A grammar finding is not that: within one line the arm index, the
+ * production, its first set and the annotation all mean different things, and the
+ * annotation is the part that should be shouting. So a line here is a list of SPANS, and
+ * a styled line is a linecraft `Grid` of `Styled` cells — which also gives the columns
+ * their alignment for free.
+ *
+ * THE INVARIANT THAT MUST NOT BREAK
+ * ---------------------------------
+ * Padding happens in ONE place, before either path sees it, and the plain form is the
+ * concatenation of the padded span texts. So the two paths differ in styling and in
+ * nothing else — not in width, not in alignment, not in content. No escape byte is
+ * produced at all when colour is off, so the diffable output is byte-stable by
+ * construction rather than by stripping. `width` is passed explicitly and defaults to 80
+ * off-TTY, so a piped run cannot vary with the terminal it was piped from.
+ */
+import { type TextStyle } from 'linecraft';
+export type Tone = TextStyle;
+/**
+ * Semantic tones, named once so the two renderers cannot drift apart.
+ *
+ * The ladder matters more than the individual colours: within a finding, exactly one
+ * thing should be the brightest, and provenance / accept keys / byte costs should
+ * recede. A report where everything is emphasised is a report where nothing is.
+ */
+export declare const TONE: {
+    /** The single most important thing in its block. */
+    readonly loud: Tone;
+    /** A heading, a count, the thing being named. */
+    readonly strong: Tone;
+    /** Supporting detail — never the finding itself. */
+    readonly quiet: Tone;
+    /** Recedes furthest: provenance, snapshot keys, byte costs. */
+    readonly faint: Tone;
+    /** This span IS the problem. */
+    readonly bad: Tone;
+    /** Real, but not blocking. */
+    readonly warn: Tone;
+    /** A location or an identifier the reader will search for. */
+    readonly ident: Tone;
+    /** Clean, or the thing to do. */
+    readonly good: Tone;
+    /** Structure: rules, box drawing, group frames. */
+    readonly frame: Tone;
+};
+/** One styled run of text. `width` pads it, in BOTH paths, so columns line up. */
+export type Span = {
+    text: string;
+    style?: Tone;
+    /** Pad to this column width. Applied once, before either path renders. */
+    width?: number;
+    /** Text that ALREADY contains escapes (a linecraft component's own output). */
+    raw?: boolean;
+    /**
+     * Absolute path this span points at. In the STYLED path it becomes a clickable
+     * terminal hyperlink; the plain path ignores it entirely, which is what keeps the
+     * diffable output free of escapes and of absolute paths.
+     */
+    link?: string;
+};
+/** A line is its spans. An empty array is a blank line. */
+export type Line = Span[];
+export declare const t: (text: string, style?: Tone, width?: number) => Span;
+export declare const blank: () => Line;
+/** A horizontal rule. Segmentation is what turns eighty undifferentiated lines into a
+ *  handful of blocks a reader can skip between. */
+export declare const rule: (width: number, style?: Tone, char?: string) => Line;
+export type RenderTarget = {
+    /** Emit ANSI. Default false — never sniffed here; the CLI decides. */
+    color?: boolean;
+    /** Columns. Default 80, which is also what an off-TTY stream reports as nothing. */
+    width?: number;
+    /**
+     * Emit OSC-8 terminal hyperlinks on file locations. Only meaningful with `color`,
+     * since both are escape sequences. Default: on when colouring. A terminal without
+     * OSC-8 support prints the URL as visible junk, so this is the escape hatch.
+     */
+    links?: boolean;
+};
+export declare const DEFAULT_WIDTH = 80;
+/** Plain text of a line list — the byte-stable form, produced without a terminal. */
+export declare const plain: (lines: readonly Line[]) => string;
+/**
+ * Lines → a string. Without colour this never constructs a Region at all, so nothing on
+ * the diffable path depends on linecraft's environment detection.
+ */
+export declare function render(lines: readonly Line[], target?: RenderTarget): string;
+export type CodeFrame = {
+    /** Path as the reader should see it — relative, so no absolute path can be diffed. */
+    path: string;
+    /** Absolute path, used ONLY for the terminal hyperlink, which the plain form strips. */
+    fullPath: string;
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+    lineBefore?: string | null;
+    lineText: string;
+    lineAfter?: string | null;
+    message: string;
+    /** Short label attached to the underline — the one sentence the caret is making. */
+    shortMessage?: string;
+    type?: 'error' | 'warning' | 'info';
+};
+/**
+ * A source frame with the caret under the offending span — linecraft's `CodeDebug`, the
+ * same component jess renders its compiler errors with.
+ *
+ * Its lines come back as RAW spans: the component styles per token, which a span list
+ * cannot describe, and it is already the shape a reader wants. The plain form is
+ * recovered by stripping — the one place in this file that has to — and is asserted
+ * escape-free and absolute-path-free by test.
+ */
+export declare function codeFrame(frame: CodeFrame, target?: RenderTarget, indent?: string): Line[];
+/** Deterministic thousands grouping — `toLocaleString()` differs between machines. */
+export declare function groupDigits(n: number): string;
+export declare const pad: (s: string, w: number) => string;
+/** Hard-wrap on spaces at `width`, prefixing every line with `indent`. */
+export declare function wrap(text: string, width: number, indent: string): string[];
+//# sourceMappingURL=terminal.d.ts.map

package/dist/analysis/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/analysis/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,WAAW,CAAA;AAErE,MAAM,MAAM,IAAI,GAAG,SAAS,CAAA;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;IACf,oDAAoD;aACpD,IAAI,EAAwC,IAAI;IAChD,iDAAiD;aACjD,MAAM,EAAoB,IAAI;IAC9B,oDAAoD;aACpD,KAAK,EAA8B,IAAI;IACvC,+DAA+D;aAC/D,KAAK,EAAyC,IAAI;IAClD,gCAAgC;aAChC,GAAG,EAAsB,IAAI;IAC7B,8BAA8B;aAC9B,IAAI,EAAyB,IAAI;IACjC,8DAA8D;aAC9D,KAAK,EAAmC,IAAI;IAC5C,iCAAiC;aACjC,IAAI,EAAwB,IAAI;IAChC,mDAAmD;aACnD,KAAK,EAAuB,IAAI;CACxB,CAAA;AAEV,kFAAkF;AAClF,MAAM,MAAM,IAAI,GAAG;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,2DAA2D;AAC3D,MAAM,MAAM,IAAI,GAAG,IAAI,EAAE,CAAA;AAEzB,eAAO,MAAM,CAAC,SAAU,MAAM,UAAU,IAAI,UAAU,MAAM,KAAG,IACmC,CAAA;AAElG,eAAO,MAAM,KAAK,QAAO,IAAU,CAAA;AAEnC;mDACmD;AACnD,eAAO,MAAM,IAAI,UAAW,MAAM,UAAS,IAAI,oBAA4B,IACvB,CAAA;AAEpD,MAAM,MAAM,YAAY,GAAG;IACzB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,aAAa,KAAK,CAAA;AA0B/B,qFAAqF;AACrF,eAAO,MAAM,KAAK,UAAW,SAAS,IAAI,EAAE,KAAG,MACkB,CAAA;AA8FjE;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,MAAM,GAAE,YAAiB,GAAG,MAAM,CAYhF;AASD,MAAM,MAAM,SAAS,GAAG;IACtB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAA;IACZ,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;CACpC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,GAAE,YAAiB,EAAE,MAAM,SAAK,GAAG,IAAI,EAAE,CA0B1F;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED,eAAO,MAAM,GAAG,MAnNE,MAAM,KAAK,MAAM,KAAG,MAmNd,CAAA;AAExB,0EAA0E;AAC1E,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAY1E"}