parseman 0.44.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

@@ -0,0 +1,133 @@
+/**
+ * The DELIBERATE grammar diagnostic — the one call that asks parseman "is anything
+ * wrong with this grammar?" and answers in a form a machine can gate on.
+ *
+ * Why this exists as its own entry point, and why nothing in `compile()` prints any
+ * more: a diagnostic that rides along with the thing that produces the artifact is a
+ * diagnostic nobody chose to run. Importing one example grammar used to print ~51
+ * lines of gating advice through `console.warn` before a single byte was parsed —
+ * advice that was correct, detailed, and read by no one, because it arrived unasked
+ * in the middle of an unrelated build log. The same principle is already settled one
+ * layer down for codegen ("anything 'diagnostic' doesn't end up in codegen"); this is
+ * that principle applied at build time. Compiling produces an artifact and says
+ * nothing. Asking for a diagnosis produces a diagnosis.
+ *
+ * Design rules this surface holds itself to:
+ *
+ *  1. MACHINE-READABLE FIRST. `diagnoseGrammar()` returns a plain, JSON-serializable
+ *     object with a versioned `schema` tag. The human rendering is a separate,
+ *     optional function over that object — never the primary product. A CI job gates
+ *     on `ok`; a person reads `formatGrammarDiagnosis()`.
+ *  2. DETERMINISTIC. Findings are sorted by (severity, code, id). Two runs over the
+ *     same grammar produce byte-identical JSON, so a diagnosis can be committed as a
+ *     snapshot and diffed.
+ *  3. FAILS CLOSED. An analysis that could not run is NOT a pass. `unanalysable` stays
+ *     authoritative (see `GatingReport.unanalysable`), it is a BLOCKING finding, and a
+ *     diagnosis whose analysis THREW is reported as a blocking finding rather than as
+ *     an empty, clean-looking report.
+ *  4. ONE ENTRY POINT. It accepts a combinator, a rule-name→combinator map, a `rules()`
+ *     map, or a `compose()` result, and figures out which it got. Choosing between
+ *     `analyzeGating` / `analyzeGatingRules` / `analyzeGrammarGating` is exactly the
+ *     kind of decision that makes people not bother.
+ */
+import type { Combinator } from '../types.ts';
+import { type AnalyzeGatingOptions, type GatingReport } from './gating.ts';
+import { type AnalysableGrammar } from './grammar.ts';
+import { type Degradation } from '../compiler/degradation.ts';
+/** Anything `diagnoseGrammar()` knows how to read. */
+export type DiagnosableGrammar = Combinator<unknown> | AnalysableGrammar | ReadonlyArray<readonly [string, Combinator<unknown>]>;
+/**
+ * `blocking` fails `ok` (and therefore a CI gate). `advisory` is reported but does not
+ * fail: the author either already acknowledged it (`accepted`) or has nothing to act on.
+ */
+export type DiagnosisSeverity = 'blocking' | 'advisory';
+/** Stable, greppable finding class. New codes may be added; existing ones are not renamed. */
+export type DiagnosisCode = 
+/** A hot choice with no first-char dispatch — every position enters doomed arms. */
+'ungated-choice'
+/** An API-misuse pattern in a choice's arms (double-not, leading-not, keyword-regex). */
+ | 'anti-pattern'
+/** Part of the grammar could not be examined. A clean report over it is NOT a pass. */
+ | 'unanalysable'
+/** The compiler took a correct-but-slower path. Mirrors the `[parseman] degraded` channel. */
+ | 'degraded'
+/** An `accept` entry that matched no ungated choice — a stale snapshot line to prune. */
+ | 'stale-accept';
+export type DiagnosisFinding = {
+    /** Stable identity: the choice id, `rule#arm`, the rule name, or the degradation code. */
+    id: string;
+    code: DiagnosisCode;
+    severity: DiagnosisSeverity;
+    /** Rule / node type the finding lands on. */
+    rule: string;
+    /** One-line statement of what is wrong. */
+    message: string;
+    /** Arm-level evidence and concrete fixes, one entry per contributing cause. */
+    details: string[];
+    /** The `accept` snapshot key that would silence this finding, when one exists. */
+    acceptKey?: string;
+};
+export type GrammarDiagnosis = {
+    /** Versioned so a committed snapshot can be migrated rather than silently reinterpreted. */
+    schema: 'parseman.diagnosis/1';
+    /**
+     * True only when there is no blocking finding. A CI gate is
+     * `process.exit(diagnoseGrammar(g).ok ? 0 : 1)` — nothing else to remember.
+     */
+    ok: boolean;
+    summary: {
+        totalChoices: number;
+        gated: number;
+        recoverable: number;
+        ungated: number;
+        accepted: number;
+        deferred: number;
+        antiPatterns: number;
+        unanalysable: number;
+        degraded: number;
+        staleAccepts: number;
+    };
+    /** Sorted (severity, code, id). Deterministic across runs. */
+    findings: DiagnosisFinding[];
+    /**
+     * Every blocking-choice id, sorted — paste straight into `{ accept: [...] }` to
+     * acknowledge the current state as intentional.
+     */
+    acceptSnapshot: string[];
+    /** The full underlying gating report, for callers that want the raw per-choice detail. */
+    gating: GatingReport;
+    /**
+     * Degradations recorded WHILE this analysis ran (e.g. an opaque composed artifact).
+     * NOT the compile-time set — compiling is a separate act; see `PARSEMAN_DEGRADATION`.
+     *
+     * Empty when `PARSEMAN_DEGRADATION=off`, because `recordDegradation` short-circuits on
+     * the level. That is not a blind spot: everything this analysis can record is ALSO
+     * present in `gating.unanalysable`, which no env var can switch off.
+     */
+    degradations: Degradation[];
+};
+export type DiagnoseOptions = Pick<AnalyzeGatingOptions, 'accept' | 'entryName'>;
+/**
+ * Diagnose a grammar. Never throws: an analysis that cannot run is reported as a
+ * blocking `unanalysable` finding, because a thrown diagnostic and a clean grammar
+ * 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

@@ -0,0 +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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAE5D;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAmCpE"}