parseman 0.45.0 → 0.46.0

package/dist/analysis/corpus.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The SECOND world.
+ *
+ * A type error has one source to point at. A grammar finding has two — the ordered
+ * choice whose arms cost the time, and the input that pays for it — and relating them is
+ * the whole diagnostic. `gating.ts` owns the first world and is entirely static. This
+ * module owns the second, and it is deliberately the smallest honest thing that can be
+ * said about a corpus without instrumenting a parse.
+ *
+ * WHAT IS MEASURED, EXACTLY
+ * -------------------------
+ * For a choice, every corpus POSITION whose character is in some arm's first set. That
+ * is a count of characters, not of times the choice was reached, and the difference
+ * matters: a choice nested three rules deep is reached far less often than its first
+ * characters occur. So the number is reported as what it is — an upper bound on entries,
+ * derived from the same first sets the compiler dispatches on — and never as "this
+ * choice ran N times". Naming it precisely is what keeps it useful; a number that
+ * overstates itself is worse than no number, because the reader stops trusting all of
+ * them.
+ *
+ * The one thing this DOES settle, exactly and without any modelling: an arm whose first
+ * set is ANY is entered at every one of those positions, because no first character can
+ * exclude it. That is the cost the fix removes, and it is arithmetic, not a guess.
+ *
+ * Determinism: counts and the located example are a pure function of (report, corpus).
+ * No timings, no paths beyond the caller's own sample names.
+ */
+import type { Combinator, FirstSet } from '../types.ts';
+import type { ChoiceGating } from './gating.ts';
+export type CorpusSample = {
+    name: string;
+    text: string;
+};
+/** A located input position: the caller's sample name plus 1-based line/column. */
+export type CorpusSite = {
+    sample: string;
+    line: number;
+    column: number;
+    /** The source line, untrimmed, for a caret rendering. */
+    lineText: string;
+};
+export type ArmCorpusCost = {
+    index: number;
+    /** ANY first set — no character excludes this arm. */
+    any: boolean;
+    /**
+     * Corpus positions whose character this arm's first set accepts. For an `any` arm this
+     * equals the choice total, which is the point.
+     */
+    positions: number;
+    /** The first such position, for the two-world rendering. Absent when there are none. */
+    firstSite?: CorpusSite;
+};
+export type ChoiceCorpusCost = {
+    choiceId: string;
+    /** Positions whose character SOME arm accepts — the choice's own reach, bounded. */
+    positions: number;
+    /** Every position in the corpus, so a share can be read. */
+    corpusPositions: number;
+    arms: ArmCorpusCost[];
+};
+/**
+ * Measure one choice against a corpus. `choice.anyArms` already knows which arms are
+ * broad; this adds how much input that costs.
+ */
+export declare function measureChoiceCost(c: ChoiceGating, samples: readonly CorpusSample[], arms: readonly {
+    firstSet: FirstSet;
+}[]): ChoiceCorpusCost;
+/** The per-arm first sets a choice dispatches on, in arm order. */
+export declare function armFirstSets(choiceArms: readonly Combinator<unknown>[]): {
+    firstSet: FirstSet;
+}[];
+//# sourceMappingURL=corpus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../../src/analysis/corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEzD,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,GAAG,EAAE,OAAO,CAAA;IACZ;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,SAAS,CAAC,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,aAAa,EAAE,CAAA;CACtB,CAAA;AAyBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,EAAE,GAAG,gBAAgB,CAiC9I;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,EAAE,CAEjG"}

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

@@ -0,0 +1,65 @@
+/**
+ * The human layer over `GrammarDiagnosis`.
+ *
+ * Three layers, not two: `gating.ts`/`corpus.ts` produce data, `diagnose.ts` decides
+ * `ok` (the CI verdict), and this file makes either readable. Nothing here computes a
+ * finding and nothing here decides pass or fail. A gate consumes the object; a person
+ * reads this. If a number appears below that is not in the report, that is a bug here.
+ *
+ * GROUPED BY CAUSE, NOT BY SITE
+ * -----------------------------
+ * The first version grouped by site: thirteen findings, each carrying its own copy of
+ * the explanation, the `do` line and the `ok as-is?` line. Measured on
+ * `examples/css/parser.ts`, that was three distinct explanations rendered nine times
+ * across 146 lines. Density that comes from repetition is not detail — it is the same
+ * sentence again, and it buries the arm tables, which are the part a reader acts on.
+ *
+ * A cause is now stated ONCE, given a glyph, and followed by its sites. That also
+ * disposes of the question a glossary would have answered: the glyph is defined at the
+ * head of the only group it labels, so there is nothing to look up. Shipping a glossary
+ * AND the inline explanations would just re-create the duplication this removes.
+ *
+ * WHAT CARRIES MEANING
+ * --------------------
+ *   colour  — severity, and importance WITHIN a finding. Exactly one span per block is
+ *             the brightest thing in it; provenance and accept keys recede.
+ *   glyph   — the cause class, so sites are scannable without reading prose.
+ *   rules   — group boundaries, so the report is blocks rather than a paragraph.
+ *   columns — the arm table is aligned, so an ANY arm or an overlap is visible as a
+ *             shape before it is read as text.
+ *
+ * All of that lives in the STYLED path. The plain path is the same content with the same
+ * padding and no escapes, so `docs/samples/` stays diffable and the two cannot drift.
+ */
+import { type GrammarDiagnosis } from './diagnose.ts';
+import type { ChoiceCorpusCost } from './corpus.ts';
+import { groupDigits, type Line, type RenderTarget } from './terminal.ts';
+export type DiagnoseRenderOptions = RenderTarget & {
+    /** Grammar label for the header. The CLI passes a cwd-relative path. */
+    name?: string;
+    /** Sites to expand. Default 20; the report always holds all of them. */
+    limit?: number;
+    /** Corpus cost per choice id, from `measureChoiceCost`. */
+    cost?: ReadonlyMap<string, ChoiceCorpusCost>;
+    /** Per-arm first-set renderings per choice id, in arm order. */
+    armFirstSets?: ReadonlyMap<string, readonly string[]>;
+    /** Per-arm leading-term labels per choice id, in arm order. */
+    armLabels?: ReadonlyMap<string, readonly string[]>;
+    /** Absolute corpus root, used ONLY for the frame's terminal hyperlink. */
+    corpusRoot?: string;
+    /**
+     * Finding ids for which `proposeFixes` PROVED a rewrite — applied it, recompiled, and
+     * re-parsed the corpus with identical output. Only these may carry the wrench. A
+     * candidate that was proposed and rejected must never appear here: offering a fix that
+     * does not exist would destroy the one guarantee the feature has.
+     */
+    fixable?: ReadonlySet<string>;
+    /** The command that would apply them, printed verbatim so nobody has to guess it. */
+    fixCommand?: string;
+};
+export { groupDigits };
+/** The lines a diagnosis renders to — data, so a caller can compose them into a larger
+ *  report without going through a string. */
+export declare function diagnosisLines(d: GrammarDiagnosis, opts?: DiagnoseRenderOptions): Line[];
+export declare function renderDiagnosis(d: GrammarDiagnosis, opts?: DiagnoseRenderOptions): string;
+//# sourceMappingURL=diagnose-render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose-render.d.ts","sourceRoot":"","sources":["../../src/analysis/diagnose-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAmB,KAAK,gBAAgB,EAAyB,MAAM,eAAe,CAAA;AAC7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EACkC,WAAW,EAClD,KAAK,IAAI,EAAE,KAAK,YAAY,EAC7B,MAAM,eAAe,CAAA;AAEtB,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG;IACjD,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IAC5C,gEAAgE;IAChE,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA;IACrD,+DAA+D;IAC/D,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA;IAClD,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7B,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,OAAO,EAAE,WAAW,EAAE,CAAA;AA8ItB;6CAC6C;AAC7C,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,GAAE,qBAA0B,GAAG,IAAI,EAAE,CAmL5F;AAuFD,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,GAAE,qBAA0B,GAAG,MAAM,CAE7F"}

package/dist/analysis/diagnose.d.ts

@@ -113,6 +113,21 @@ export type DiagnoseOptions = Pick<AnalyzeGatingOptions, 'accept' | 'entryName'>
  * must not look the same to a caller that wrapped this in a try/catch.
  */
 export declare function diagnoseGrammar(grammar: DiagnosableGrammar, opts?: DiagnoseOptions): GrammarDiagnosis;
+/**
+ * The analysis examined NOTHING: no choice was walked, and rules were skipped.
+ *
+ * This is NOT "problems were found" and must never be presented as a finding count. A
+ * diagnosis over a fully opaque grammar has one blocking finding per skipped rule, which
+ * `findings.length` then reports as "176 problems, 176 failing the check" — a sentence
+ * that reads as 176 discovered defects and actually means the tool inspected zero
+ * choices. `ok` is correctly false either way, so `ok` alone cannot tell the two apart;
+ * a caller that needs to distinguish "measured, and it is bad" from "could not measure"
+ * asks here. The CLI maps this to exit 2 (COULD NOT ANALYSE), not exit 1.
+ *
+ * `unanalysable > 0` is required, so a genuinely choice-free grammar (nothing to walk,
+ * nothing skipped) stays an ordinary clean pass rather than a measurement failure.
+ */
+export declare function examinedNothing(d: GrammarDiagnosis): boolean;
 /** Render a diagnosis for a human. The structured object stays the product of record. */
 export declare function formatGrammarDiagnosis(d: GrammarDiagnosis): string[];
 //# sourceMappingURL=diagnose.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/analysis/diagnose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAEL,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAC7C,MAAM,aAAa,CAAA;AACpB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAEc,KAAK,WAAW,EACpC,MAAM,4BAA4B,CAAA;AAEnC,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAC1B,UAAU,CAAC,OAAO,CAAC,GACnB,iBAAiB,GACjB,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAEzD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,CAAA;AAEvD,8FAA8F;AAC9F,MAAM,MAAM,aAAa;AACvB,oFAAoF;AAClF,gBAAgB;AAClB,yFAAyF;GACvF,cAAc;AAChB,uFAAuF;GACrF,cAAc;AAChB,8FAA8F;GAC5F,UAAU;AACZ,yFAAyF;GACvF,cAAc,CAAA;AAElB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0FAA0F;IAC1F,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4FAA4F;IAC5F,MAAM,EAAE,sBAAsB,CAAA;IAC9B;;;OAGG;IACH,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE;QACP,YAAY,EAAE,MAAM,CAAA;QACpB,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,OAAO,EAAE,MAAM,CAAA;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,MAAM,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,8DAA8D;IAC9D,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,0FAA0F;IAC1F,MAAM,EAAE,YAAY,CAAA;IACpB;;;;;;;OAOG;IACH,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,WAAW,CAAC,CAAA;AAQhF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAqBrG;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA+BpE"}
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/analysis/diagnose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAEL,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAC7C,MAAM,aAAa,CAAA;AACpB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAEc,KAAK,WAAW,EACpC,MAAM,4BAA4B,CAAA;AAEnC,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAC1B,UAAU,CAAC,OAAO,CAAC,GACnB,iBAAiB,GACjB,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAEzD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,CAAA;AAEvD,8FAA8F;AAC9F,MAAM,MAAM,aAAa;AACvB,oFAAoF;AAClF,gBAAgB;AAClB,yFAAyF;GACvF,cAAc;AAChB,uFAAuF;GACrF,cAAc;AAChB,8FAA8F;GAC5F,UAAU;AACZ,yFAAyF;GACvF,cAAc,CAAA;AAElB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0FAA0F;IAC1F,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4FAA4F;IAC5F,MAAM,EAAE,sBAAsB,CAAA;IAC9B;;;OAGG;IACH,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE;QACP,YAAY,EAAE,MAAM,CAAA;QACpB,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,OAAO,EAAE,MAAM,CAAA;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,MAAM,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,8DAA8D;IAC9D,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,0FAA0F;IAC1F,MAAM,EAAE,YAAY,CAAA;IACpB;;;;;;;OAOG;IACH,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,WAAW,CAAC,CAAA;AAQhF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAqBrG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAE5D;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAmCpE"}