parseman 0.45.0 → 0.47.0

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"}