@nodegx/export 0.0.0-stage → 0.2.5

package/dist/emit/parseLib.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `src/lib/parse.ts` — `Parse CSV`, `To CSV`, `Parse XML` and `Parse Feed`, emitted into the app (EXP-011 §75).
+ *
+ * The same shape as {@link ./utilLib.ts}: constant text, shipped only where a component calls into it, and a
+ * **separate** module from `util.ts` on that file's own rule (a project that formats a string should not ship
+ * a CSV tokeniser, and an XML parser even less). The four are `util-call`s in the plan — each node is a
+ * function of its inputs and holds nothing else — with one difference from the three small utilities:
+ * every one of them has SEVERAL value outputs, so the call carries the output port's name as its trailing
+ * literal argument (`DATE_NODES`' selector, one family over) and the helper answers that port. A one-entry
+ * memo inside each helper keeps a page that reads three outputs of one node to one parse.
+ *
+ * A transcription of three runtime modules and four node files:
+ *
+ * - `noodl-runtime/src/csv.ts` — `stripBOM`, the contiguity-checking `tokenise`, `parseCSV` (the
+ *   unterminated-quote sentence verbatim), `rowsToRecords`, `unionOfKeys`, `quoteCell`, `toCSV`, `rowsToCSV`.
+ * - `data/parsecsv.ts` / `data/tocsv.ts` — the abstain (`textSupplied` / `itemsSupplied`: nothing arrived ⇒
+ *   no Items, Count 0, no Error — Failure Contract §2), the setters' fallbacks (`delimiter || ','`,
+ *   `!!hasHeader`, a `stringlist` Columns split on commas and trimmed), rows-of-cells written cell for cell.
+ * - `noodl-runtime/src/xml.ts` — `scanForHostileConstructs` (the two refusals, sentences verbatim) and
+ *   `parseXML` over **`fast-xml-parser` at the interpreter's own pin, 4.5.7**, with the interpreter's own
+ *   options. 🔴 The one third-party dependency an emitted lib has ever declared: FED-001 R1 took the library
+ *   over a hand-rolled scanner for the runtime (entity expansion is a denial-of-service hole, not a wrong
+ *   answer), and a transcription of an XML parser would be a second parser that drifts — so
+ *   {@link PARSE_DEPENDENCIES} is added to the exported `package.json` exactly when a component calls
+ *   `parseXml` or `parseFeed`.
+ * - `noodl-runtime/src/feed.ts` — the whole module: RSS/Atom/RDF detection (RDF first, its `<item>` a
+ *   SIBLING of `<channel>`), the readers, `toISODate`'s retry, the Atom link family, images, enclosures,
+ *   tags, authors, the identity ladder and FNV-1a `hashId`. 🔴 **The ladder's separator is a NUL byte.**
+ *   `feed.ts:365` holds a literal U+0000 between the quotes, which every editor draws as a space; the
+ *   transcription writes `'\u0000'` because FED-002's unique index keys on the id and a space would mint a
+ *   different id for every item on the hash rung. Found by the §A differential, not by reading.
+ *
+ * ⚠️ **The one divergence, and where it is reported.** On a FAILED parse the interpreter keeps the previous
+ * successful answer on its value outputs beside the Error (`items` is "replaced only on a successful
+ * parse"); a pure call has no previous answer, so Items is absent and Count is 0 beside the Error. The
+ * planner files a note at every parse node whose text arrives by wire — a literal cannot have a previous
+ * parse. On a FIRST failure the two agree exactly.
+ *
+ * `Changed` and `Failure` are recomputation pulses and defer with the date family's sentence
+ * ({@link PARSE_SIGNAL_SENTENCES}); a wire off one is not a chain the export can hang anything on.
+ */
+/** Where the module lands in the exported app. */
+export declare const PARSE_LIB_PATH = "src/lib/parse.ts";
+/** The exported helpers, one per node. Sorted — the import list is sorted too. */
+export declare const PARSE_HELPERS: readonly ["parseCsv", "parseFeed", "parseXml", "toCsv"];
+export type ParseHelper = (typeof PARSE_HELPERS)[number];
+export declare function isParseHelper(fn: string): fn is ParseHelper;
+/**
+ * The npm dependency the exported app takes on when XML is parsed — the interpreter's own pin
+ * (`noodl-runtime/package.json`, `xml.ts`'s module comment measured 4.5.7 at 230 KB unpacked with one dep
+ * against 5.x's 1.3 MB with six). Exact, not a caret, so the exported app and the interpreter read one parser.
+ */
+export declare const PARSE_DEPENDENCIES: Readonly<Record<string, string>>;
+/** Which helpers need {@link PARSE_DEPENDENCIES}. `parseCsv` and `toCsv` need nothing. */
+export declare const PARSE_HELPERS_NEEDING_DEPENDENCY: ReadonlySet<string>;
+/**
+ * Per output port: the static TypeScript type the helper's overload answers (`exprTsType`'s vocabulary —
+ * `unknown` wherever the value can be `undefined`, for `dateToString`'s reason: a single-placeholder String
+ * Format collapses a `string`-typed expression to the bare value, and that would print the word
+ * "undefined" where the interpreter substitutes `''`), and whether it can be `undefined` at all
+ * (`maybeUndefinedExpr`'s table, one family over).
+ *
+ * 🔴 Must agree with the overloads in {@link parseLibSource}. `items` is `any[]` on both CSV and Feed —
+ * the CSV rows' shape depends on Has Header, and the feed rows are typed inside the module only, so the
+ * emitted component never has to name a type it does not import. {@link FEED_ITEM_FIELDS} is what lets a
+ * repeater over a feed drop a mapped field the rows do not carry, by name.
+ */
+export declare const PARSE_OUTPUTS: Readonly<Record<ParseHelper, Readonly<Record<string, {
+    tsType: string;
+    maybeUndefined: boolean;
+}>>>>;
+/** The fields every feed item carries (`FeedItem` in the emitted module; `parsefeed.ts`'s Items description). */
+export declare const FEED_ITEM_FIELDS: readonly string[];
+/**
+ * The selector a `util-call` into this module carries: its trailing literal argument. `undefined` for a
+ * call that is not a parse helper, or whose last argument is not a string literal — neither can be built by
+ * the planner, so a lookup that answers `undefined` is a programming error upstream, not an authored shape.
+ */
+export declare function parseSelectorOf(expr: {
+    fn: string;
+    args: ReadonlyArray<{
+        kind: string;
+        value?: unknown;
+    }>;
+}): string | undefined;
+/** `exprTsType` for a parse call — `unknown` for a selector the table does not know, never a throw. */
+export declare function parseOutputTsType(fn: ParseHelper, selector: string | undefined): string;
+/** `maybeUndefinedExpr` for a parse call — `true` for a selector the table does not know: the guarded answer. */
+export declare function parseOutputMayBeUndefined(fn: ParseHelper, selector: string | undefined): boolean;
+/**
+ * The deferral sentence for a signal output consumed as a wire — the date family's `DATE_SIGNAL_OUTPUTS`,
+ * one family over, and for the same reason: `Changed` and `Failure` announce a recomputation, and a
+ * recomputation in the emitted component is a render, not an event a chain can hang off. `Failure` is a
+ * value this slice renders as an absent one (the Error output) rather than a pulse it can fire.
+ */
+export declare const PARSE_SIGNAL_SENTENCES: Readonly<Record<string, string>>;
+/**
+ * The module's source.
+ *
+ * ⚠️ A plain string array rather than a template literal, for `dateLib.ts`'s stated reason: the emitted body
+ * needs no interpolation, and keeping it out of an interpolation context means a future edit cannot
+ * accidentally interpolate the generator's own scope into the exported app. Generated from a real `.ts`
+ * file that was typechecked under the exported app's own strict options and graded against the runtime
+ * modules by `tests/the-parsers.test.ts` §A; edit the strings and the test grades the edit.
+ */
+export declare function parseLibSource(): string;

package/dist/emit/preflight.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The pre-flight summary — EXP-004's *before you export* surface.
+ *
+ * ## What this is for
+ *
+ * `EXPORT-REPORT.md` (see {@link module:emit/report}) is the account an author reads *after* the
+ * export, inside the app they now own. EXP-004 asks for one more moment: **before** they pick a
+ * directory and write sixty files, tell them what they are about to get, so the decision to
+ * proceed is made with accurate expectations rather than with the word "export".
+ *
+ * Same facts, earlier moment, and much shorter — this is a thing someone reads in a dialog and
+ * then clicks a button, not a document they study.
+ *
+ * ## 🔴 It is exact, and it is deliberately not an estimate
+ *
+ * EXP-004's own wording is *"pre-flight **estimate**"*, and its testing plan asks that the
+ * estimate "match the actual outcome within a reasonable margin". **That premise does not survive
+ * contact with this pipeline, and the honest thing is to say so rather than to build a
+ * deliberately worse predictor so that a margin exists to measure.**
+ *
+ * `emitApp` is pure: it reads nothing, writes nothing, and returns the files as strings. Writing
+ * them to disk is the caller's separate act (`write/writeExport.ts`, which both front doors call).
+ * So the cost of knowing the real answer is the cost of running the generator — about a tenth of a
+ * second on every project in the corpus — and there is no reason whatever to approximate a number
+ * you can simply compute.
+ * A margin here would be a defect, not a tolerance.
+ *
+ * ⚠️ **The cheap alternative was measured before this was written, because it is the one a future
+ * session will reach for.** The obvious "estimate" is to stop after `planProject` and skip
+ * emission — that is where most refusals are decided (§20.1), and it looks like the same answer
+ * for less work. Over the seven fixtures it is **not** the same answer: the plan layer files 28
+ * refusals where the export files 32. The missing four are all decided during emission — three
+ * `parameter … has no style/content mapping` on `puppy-test-3` and one retired kit parameter on
+ * `kits` — and they are invisible to any analysis that stops before the generator runs.
+ *
+ * 🔴 **That divergence happens to be invisible at component level today, and that is a fact about
+ * the corpus rather than a property of the layers.** No fixture currently has a component whose
+ * *only* refusals are emit-layer ones, so a plan-layer pre-flight would still sort every component
+ * onto the correct side of "clean". Nothing makes that hold: a component with one unmapped
+ * `padding` and no dropped wires would be called clean and export dirty. The control pair in
+ * `tests/preflight.test.ts` asserts the two layers **disagree** on the totals, which is what keeps
+ * this paragraph honest — a cheap-layer rewrite reddens a row instead of quietly under-reporting.
+ *
+ * ## The framing rules are `report.ts`'s, and they are the actual work
+ *
+ * - **Lead with what worked.** Counts and whole components first; a project with nothing to report
+ *   never renders a list of problems, because there are none to render.
+ * - **Be specific, not statistical.** No percentages and no confidence score. Components are named
+ *   and their refusals counted.
+ * - **Never let unverified code look verified.** Nothing has been run here either — less so, in
+ *   fact, since at this point nothing has even been written.
+ *
+ * @module emit/preflight
+ */
+import { Catalog } from '../catalog';
+import { ExportIR, RefusedNode } from '../ir/types';
+import { EmittedApp } from './emitApp';
+import { BackendMode, ExportCascade } from './report';
+/** A component that will emit a file, but with refusals recorded against it. */
+export interface PreflightAttention {
+    path: string;
+    file: string;
+    /** How many nodes, wires or parameters the export will leave out of this component. */
+    refusals: number;
+    unreachable: boolean;
+    /**
+     * EXP-013 AC2 — the refused nodes themselves, by type and label, with the root that starves each
+     * silenced one. The same rows `EXPORT-REPORT.md` prints under the component.
+     */
+    nodes: RefusedNode[];
+}
+/** A component that will emit no file at all. */
+export interface PreflightNoFile {
+    path: string;
+    reason: string;
+    /**
+     * `scaffolded` is done — the app shell covers it. `deferred` is not. They are opposite news and
+     * the discriminator is carried from the two sites in `plan.ts` that know, never read back out of
+     * the sentence.
+     */
+    kind: 'scaffolded' | 'deferred';
+    /** EXP-013 AC2. The nodes the plan refused in a component that emits no file. */
+    nodes: RefusedNode[];
+}
+export interface PreflightSummary {
+    projectName: string;
+    /**
+     * EXP-013 AC3 — the refusals split into the nodes the export has no rule for and the nodes only
+     * refused because of them, with the roots named. `cascade.silenced + cascade.unsilenced` is the
+     * number of refused nodes; {@link refusals} below is the number of *lines* (nodes, wires,
+     * parameters, whole components) and stays the length of the report's list.
+     */
+    cascade: ExportCascade;
+    /**
+     * EXP-013 AC4 — the plain sentence that leads when a cascade costs a pathway (a backend verb, a
+     * navigation, an `On App Error`), or `null` when the loss is nodes rather than a pathway. The
+     * modal's button changes with it.
+     */
+    verdict: string | null;
+    /**
+     * Files the export will generate, `EXPORT-REPORT.md` included — the number the author will see
+     * in the folder afterwards.
+     */
+    generatedFiles: number;
+    /**
+     * Assets that travel byte-for-byte beside them: a kit's script, an icon set's `.woff2`,
+     * Inter's four `.ttf` (EXP-010 AC5).
+     *
+     * 🔴 **Counted separately and never folded into {@link generatedFiles}, because they are a
+     * separate channel that has already been dropped once.** `emitApp` returns `files` and `copies`
+     * as two lists, and §19.6 records the one shipped runner writing only the first — an author's
+     * fonts silently absent from their repo, every gate green. A pre-flight that promised
+     * "33 files" and delivered 45 would be describing the same defect from the other end.
+     */
+    copiedAssets: number;
+    /** Pages and components that will emit a file. */
+    pages: number;
+    components: number;
+    /** Paths of the components that will translate with nothing left over, in emission order. */
+    whole: string[];
+    /** The rest, worst first. */
+    attention: PreflightAttention[];
+    noFile: PreflightNoFile[];
+    /**
+     * Every item the export will list as not translated: each component-level refusal, each
+     * component that emits **no file at all**, each kit that contributes no nodes, and each line
+     * about the project as a whole. This is the length of the list `EXPORT-REPORT.md` will print.
+     *
+     * 🔴 **A component that emits no file is in this number, and the first draft left it out.** It
+     * counted only the refusals recorded *inside* generated components, so `puppy-test-3` announced
+     * "18" and then printed nineteen bullets — the extra being `Components/BenchLogicProbe`, which
+     * is not a node dropped from a file but a whole component with no file. That is the largest
+     * thing an export can leave out, and it was the one thing the headline number could not see.
+     */
+    refusals: number;
+    /** Components with no generated file that are *not* handled by the app shell — counted above. */
+    noFileDeferred: number;
+    backend: BackendMode;
+    backendEndpoint: string | null;
+    /** `src/api/http.ts` — real generated calls to the addresses the author typed, never stubs. */
+    httpModule: boolean;
+    /** EXP-011 §41. `src/api/functions.ts` — one function per `Cloud Function` node. */
+    functionsModule: boolean;
+    /** Kits that will ship their files but contribute none of their nodes. */
+    moduleFailures: number;
+    /** Refusals about the project rather than any one component (cloud functions, chiefly). */
+    projectRefusals: number;
+}
+/**
+ * The summary, from an export that has already been generated in memory.
+ *
+ * 🔴 **Everything here is read off `EmittedApp`, and nothing is recomputed.** The pre-flight and
+ * the report are two renderings of one set of facts; the moment this function starts deciding for
+ * itself whether a component counts as whole, the surface an author reads *before* exporting and
+ * the one they read *after* can disagree about the same project — which is the failure EXP-004's
+ * risk table calls "the report drifting out of sync with what the generators actually do",
+ * arriving through a door the risk table did not think to name.
+ */
+export declare function summarizePreflight(app: EmittedApp): PreflightSummary;
+/**
+ * Generate the app in memory and summarise it, writing nothing.
+ *
+ * This is the whole of the "pre" in pre-flight: the export runs, and its output is discarded
+ * rather than committed to a directory the author has not yet chosen.
+ */
+export declare function preflight(ir: ExportIR, catalog: Catalog): PreflightSummary;
+/**
+ * The pre-flight as text an author reads and then decides on.
+ *
+ * Pure, and deliberately much shorter than `renderReport` — this is read standing up. It names
+ * what will be built, names every component that will come out incomplete, and says plainly that
+ * the full reasons travel with the app rather than repeating them here.
+ */
+export declare function renderPreflight(s: PreflightSummary): string;

package/dist/emit/readme.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `README.md` — the front door of the exported repository (EXP-004).
+ *
+ * ## Why this is a second file and not a section of the report
+ *
+ * They are reached by different routes and answer different questions.
+ *
+ * `EXPORT-REPORT.md` is the **record**: every node, wire and parameter the export refused, in the
+ * exporter's own words. It is what the `TODO(export)` markers in the code point at, and it is
+ * complete by construction — a reader arrives at it already looking for one specific thing.
+ *
+ * This file is what someone opens **first**, usually without having been sent anywhere. It has to
+ * answer *what is this*, *how do I run it*, *what is missing*, *what do I do about it* and *can I
+ * edit it* — and then get out of the way. It states no refusal individually; it says how many
+ * there are and sends the reader next door.
+ *
+ * ## 🔴 It is emitted for every export, and it did not used to be
+ *
+ * Until EXP-004 the README was written inside `apiModules`, under `backend !== undefined &&
+ * hasApi` — so it arrived only for a project with a NodeGX backend *and* something that queried
+ * it. Six of the seven corpus fixtures got no README at all, which is the file a developer opens
+ * first being absent from the export in the ordinary case. It is now emitted beside the report,
+ * from the same data, unconditionally. The backend section is what became conditional.
+ *
+ * ## What it shares with the report, and what it must not
+ *
+ * The ordered next steps are **the same list**, from {@link nextSteps} — one decision, two
+ * readers, the pattern `backendMode` already establishes here. What it does not share is the
+ * itemised refusals: two full copies of that list would be two things to keep in step, and the
+ * one that drifted would be the one nobody regenerated.
+ *
+ * 🔴 **No clock, no absolute path, no random id**, for the reason `report.ts` gives at length: the
+ * generators are byte-stable, and a date line would turn every golden in the package into noise.
+ *
+ * @module emit/readme
+ */
+import { ExportReportData } from './report';
+export declare const README_PATH = "README.md";
+/** Just the two fields the README prints; the IR record carries more, and none of it belongs here. */
+export interface ReadmeBackend {
+    endpoint: string;
+    appId: string;
+}
+/**
+ * The README, as Markdown.
+ *
+ * Pure. `backend` is read only when {@link backendMode} says `connected` — a project can declare
+ * cloud services and never query them, and an env-var section for a `src/api/client.ts` that was
+ * never emitted would be instructions for configuring nothing.
+ */
+export declare function renderReadme(data: ExportReportData, backend: ReadmeBackend | null): string;

package/dist/emit/report.d.ts

@@ -0,0 +1,309 @@
+/**
+ * `EXPORT-REPORT.md` — the report the exported app carries with it (EXP-004).
+ *
+ * ## Why this file exists
+ *
+ * Two generated `TODO(export)` markers have ended with *"See the export report"* since EXP-002,
+ * and there was no report. Everything the export dropped or refused went to `EmittedApp.notes`,
+ * which the runner printed to **stderr** — so an author who ran the export and opened
+ * the repo saw markers pointing at a document that did not exist, and a scrollback they no longer
+ * had. This is that document, written into the app beside the code it is about.
+ *
+ * ## The framing rules, which are the actual work
+ *
+ * EXP-004's own words, and each one is visible in the output below:
+ *
+ * - **Lead with what worked.** A report opening on a list of problems reads as failure even when
+ *   the export went well. The counts and the whole-component list come first, and a project with
+ *   nothing to report never renders an "attention" section at all.
+ * - **Be specific, not statistical.** No percentages and no confidence score. Every refusal is a
+ *   named component, a named node or wire, and the exporter's own sentence for why.
+ * - **Never let unverified code look verified.** ⚠️ This is the one that constrains wording
+ *   hardest, and the honest statement today is *narrower* than EXP-004 anticipated: EXP-003's AI
+ *   translation and trace verification do not exist yet, so nothing in a generated app has been
+ *   run, replayed or compared against anything. The report says that in those words. When
+ *   EXP-003 lands, this section gains a verdict per translation — it must not gain the word
+ *   "verified" before then.
+ *
+ * ## 🔴 No timestamp, and that is not an oversight
+ *
+ * The generators are deterministic (EXP-002-DETERMINISTIC-GENERATORS): the same project emits the
+ * same bytes, which is what makes the goldens a regression net and what lets a user diff two
+ * exports. A date line would change every byte-comparison in the suite and turn "nothing changed"
+ * into noise. The report carries no clock, no random id and no absolute path.
+ *
+ * ## Where the structure comes from
+ *
+ * 🔴 **Grouping is by what the caller already knew, never by reading the prose back.** `emitApp`
+ * pushes a component's notes inside the loop that owns `plan`, so scope is a fact at the push
+ * site; `skipKind` discriminates the router shell from a logic-only component because the two
+ * sentences would otherwise have to be told apart by matching their words. A report that grouped
+ * by parsing `notes` would mis-file the first time anyone reworded a refusal — and rewording
+ * refusals is the ordinary business of this package.
+ *
+ * @module emit/report
+ */
+import { RefusedNode } from '../ir/types';
+export declare const REPORT_PATH = "EXPORT-REPORT.md";
+/** One component, as the report talks about it. */
+export interface ReportComponent {
+    /** "Pages/Home", "Components/PuppyCard". */
+    path: string;
+    role: 'page' | 'component';
+    /** The file it emitted, or `null` when it emitted none. */
+    file: string | null;
+    /**
+     * Everything dropped or deferred inside it, in emission order, with the exporter's own
+     * reason. Already stripped of the `"<path>: "` prefix the emitter writes onto each one.
+     */
+    notes: string[];
+    /**
+     * No route reaches this component. Reported, never acted on — it changes how the notes above
+     * read (a refusal in unreachable code is not a gap in the export's reach), so it is stated
+     * beside them rather than filtering them out.
+     */
+    unreachable: boolean;
+    /** Set when nothing was emitted for this component at all. */
+    skipped?: {
+        kind: 'scaffolded' | 'deferred';
+        reason: string;
+    };
+    /**
+     * Authored scripts this export did not translate, on a component that emitted no file
+     * (EXP-011 §27.6).
+     *
+     * 🔴 **Only ever populated when {@link file} is `null`.** A component with a module carries the
+     * identical record as a code comment beside the node, and printing it here as well would make
+     * the report a second copy of something the repo already holds — the shape that is a duplicate
+     * before it is a check. `emitApp` fills this in its skip branch and nowhere else, so which of
+     * the two carriers holds a script is decided by whether a file exists, not by a filter.
+     */
+    preservedScripts?: Array<{
+        nodeId: string;
+        typeName: string;
+        label?: string;
+        source: string;
+    }>;
+    /**
+     * EXP-013. The nodes the plan refused in this component, each with the refused node that starves
+     * it when the refusal is a cascade. Optional so a report built by hand before EXP-013 still
+     * types; `emitApp` always sets it.
+     */
+    refusals?: RefusedNode[];
+}
+export interface ExportReportData {
+    projectName: string;
+    /** Every emitted file, so the report can count without being handed the contents. */
+    files: string[];
+    components: ReportComponent[];
+    /** `noodl_modules` folders that could not contribute their nodes; their files still ship. */
+    modules: string[];
+    /** Lines that are about the project rather than any one component. */
+    project: string[];
+    /** The backend endpoint the api modules talk to, or `null` when the project declares none. */
+    backendEndpoint: string | null;
+    /**
+     * Whether the project asks anything of a backend — a collection query, a mutation, or a session
+     * call.
+     *
+     * 🔴 **Not "were any api files emitted".** `src/api/http.ts` is emitted for an `HTTP Request`,
+     * which talks to whatever address the author typed and is real code in a project with no backend
+     * at all. Keying the stub sentence on "any api file" told a project with a working fetch and no
+     * backend that its reads answer empty — see {@link httpModule}.
+     */
+    usesBackend: boolean;
+    /** Whether `src/api/http.ts` was emitted — generated `HTTP Request` calls, never stubs. */
+    httpModule: boolean;
+    /** EXP-011 §41. Whether `src/api/functions.ts` was emitted — one function per `Cloud Function` node. Optional so a report built by hand before §41 still types. */
+    functionsModule?: boolean;
+    /**
+     * HLS-003 — stored parameters this export read the editor's way rather than the file's.
+     *
+     * Absent when the project has no node that exercises the seam, which is the common case and is
+     * why this is optional rather than a zeroed record. 🔴 **Absent means "nothing here exercises
+     * it", never "the seam is closed"** — a project with no wired control signal on one of the
+     * fifteen NDA-017 families reads absent however open the seam is.
+     */
+    settled?: {
+        parameters: number;
+        nodes: number;
+        /** Component paths, sorted — where an author would go to look. */
+        components: string[];
+    };
+    /**
+     * STY-004 AC6 — the named styles this export resolved into CSS.
+     *
+     * 🔴 **Silence was the defect.** A variant and a text style on an ordinary leaf node were both
+     * dropped, and `variant` appeared **0 times in a 1,059-line report** — so the author had no
+     * signal at all, in a report that itemises dropped wires. A link that IS carried must therefore
+     * say so out loud; an export that prints nothing here is claiming the project has no named
+     * styles, which is a checkable claim rather than an absence.
+     *
+     * Absent when the project declares no styles — every fixture in this package and all seven
+     * shipped templates.
+     */
+    styles?: StylesReport;
+}
+/** STY-004. What {@link ExportReportData.styles} counts. Every field is "resolved into CSS", not "present in the file". */
+export interface StylesReport {
+    /** `Look name (NodeType)` → how many nodes wore it. Sorted by name. */
+    looks: Array<{
+        name: string;
+        typename: string;
+        nodes: number;
+    }>;
+    /** Text style name → how many nodes resolved it. Sorted. */
+    textStyles: Array<{
+        name: string;
+        nodes: number;
+    }>;
+    /** Colour style names the project defines, sorted. Resolution is per parameter and not counted here. */
+    colors: string[];
+    /**
+     * Looks that carry `stateParameters` — hover, pressed, disabled.
+     *
+     * 🔴 **Carried in the file, NOT drawn by this export.** Naming them is the honest half of AC6:
+     * the states half of the Look model is a later task, and an author whose Look defines a hover
+     * needs to be told it did not ship rather than discover it in a browser.
+     */
+    looksWithUnemittedStates: string[];
+}
+/**
+ * Which of the three states the generated `src/api/` is in.
+ *
+ * 🔴 **One decision, two readers.** The report prints a sentence from it and the pre-flight
+ * summary (EXP-004's before-you-export surface) prints a different one, and the discriminator
+ * itself — *does the project ask anything of a backend, and did it name one* — must not exist
+ * twice. A second copy would be right until the day `usesBackend` grew a third case, and the two
+ * surfaces would then disagree about the same project in the same export.
+ */
+export type BackendMode = 'connected' | 'stubbed' | 'absent';
+export declare function backendMode(data: Pick<ExportReportData, 'usesBackend' | 'backendEndpoint'>): BackendMode;
+/** `"Pages/Home: wire x dropped"` → `"wire x dropped"`, when the prefix is this component's. */
+export declare function stripScope(path: string, note: string): string;
+/**
+ * The ordered steps as Markdown, shared by the report and the README so the two cannot format the
+ * same facts differently. Three-space continuation indent is what keeps the detail and locations
+ * inside their numbered item rather than starting a new block after it.
+ */
+/** A refused node the way a person names it: their label first, the picker's type name beside it. */
+export declare function describeNode(node: Pick<RefusedNode, 'displayName' | 'label' | 'nodeId'>): string;
+/**
+ * The reason as a person reads it. The planner's catch-all is `logic node (<typeName>)` — the
+ * exporter talking to itself, and the sentence `sweepUnreportedDeferrals` already refuses to
+ * stutter back at the author. Every other reason is a gate's own sentence and is kept verbatim.
+ */
+export declare function plainReason(node: Pick<RefusedNode, 'type' | 'reason'>): string;
+/** One root refusal and everything it silences, across the whole export. */
+export interface CascadeRoot {
+    /** The component the root sits in. */
+    path: string;
+    node: RefusedNode;
+    /** Every node whose `causedBy` resolves to this root, in report order. */
+    silences: Array<{
+        path: string;
+        node: RefusedNode;
+    }>;
+}
+/**
+ * EXP-013 AC3/AC4 — the refusals of an export, split into the ones the export has no rule for
+ * and the ones that are only refused because of them.
+ */
+export interface ExportCascade {
+    /** Refused nodes with no `causedBy`, that at least one other node names as its cause. Worst first. */
+    roots: CascadeRoot[];
+    /** Refused nodes with no `causedBy` — the roots above plus every independent refusal. */
+    unsilenced: number;
+    /** Refused nodes with a `causedBy` — the sum of every root's `silences`. */
+    silenced: number;
+    /**
+     * Nodes whose loss is a pathway rather than a feature (see `isPathwayType`) and that are lost to
+     * a cascade — as a silenced node, or as a root that is itself a pathway (an `On App Error` the
+     * export has no rule for takes the error pathway with it whether or not anything hangs off it).
+     */
+    pathway: Array<{
+        path: string;
+        node: RefusedNode;
+    }>;
+}
+/**
+ * The cascade, from the report data and nothing else.
+ *
+ * 🔴 **`silenced` + `unsilenced` is the number of refused nodes, and `silenced` is the sum of the
+ * roots' lists — asserted rather than assumed** (`tests/cascade.test.ts`), because the headline the
+ * modal prints is *"N the export has no rule for, M more silenced by them"*, and the cheap mistake
+ * is to count a silenced node on both sides. A node with two roots is listed under both and counted
+ * once.
+ */
+export declare function cascadeOf(data: Pick<ExportReportData, 'components'>): ExportCascade;
+/**
+ * EXP-013 AC4 — the sentence that leads when a cascade costs a pathway, or `null`.
+ *
+ * Plain, and the same words on the modal and in the report: *this export would be missing a
+ * pathway, not a node*. It names the roots, because the roots are what a person can act on.
+ */
+export declare function pathwayVerdict(cascade: ExportCascade): string | null;
+/** The lines under a component that name the nodes the plan refused, roots and their cascades first. */
+export declare function refusedNodeLines(refusals: RefusedNode[] | undefined, indent?: string): string[];
+export declare function renderSteps(steps: NextStep[]): string[];
+/**
+ * The report, as Markdown.
+ *
+ * Pure — it is handed everything it says and reads nothing, so the suite can drive it on data
+ * that no fixture on disk produces (a project with no gaps at all, which is the section order's
+ * hardest case and the one a corpus is least likely to contain).
+ */
+export declare function renderReport(data: ExportReportData): string;
+/**
+ * One thing the author has to do, and where.
+ *
+ * `where` is *locations*, not always files: a component the export refused entirely has no file to
+ * name, so the component's own path is what a reader can act on. The renderers do not know the
+ * difference and do not need to — both print it as a code span.
+ */
+export interface NextStep {
+    /** Imperative, one sentence, ending in a full stop. */
+    title: string;
+    /** What is broken until it is done. This is the sentence that justifies the position. */
+    detail: string;
+    /** Files or component paths, in emission order. May be empty. */
+    where: string[];
+}
+/**
+ * EXP-004's *"actionable next steps ordered by priority"*, computed once and rendered twice.
+ *
+ * ## 🔴 The ordering criterion, written down so it can be argued with
+ *
+ * **How much of the running app is missing without it, most first.** Not difficulty, not the
+ * number of refusals, and deliberately not the order the report prints its sections in — the
+ * report is organised for *looking something up*, and this list is organised for *doing the work*.
+ *
+ * 1. **Components with no file at all.** The most absent thing the export produces: a route can
+ *    lead to a component that was never written.
+ * 2. **A stubbed `src/api/`.** Every read answers empty and every write throws, across the whole
+ *    app rather than one screen.
+ * 3. **Refusals in components a route reaches.** Screens that render, missing behaviour.
+ * 4. **Refusals in components no route reaches.** The same work, but nothing runs it today — which
+ *    is the whole of why it sits below 3 rather than beside it.
+ * 5. **Kits that shipped files but contributed no nodes.**
+ * 6. **Anything the export said about the project as a whole.**
+ * 7. **Test what was generated.** Always present, always last, and the only step that is not about
+ *    something missing.
+ *
+ * ⚠️ **1 above 2 is a judgement and not a measurement.** A missing component takes out one screen;
+ * a stubbed backend takes out every data path in the app. They are ranked the way they are because
+ * "nothing was emitted" is strictly more absent than "a stub exists, and it names the node it came
+ * from" — but an author whose app is one page and six queries would reasonably reverse them. Both
+ * lines say what they cost, so the reading does not depend on the rank alone.
+ *
+ * ## What is *not* in the order
+ *
+ * Within a group, components stay in **emission order** — the order they appear in the report's
+ * own sections, so a reader can scan straight down from a step to its detail. Sorting them by
+ * refusal count was considered and rejected: it would break that correspondence to express a
+ * ranking that the counts printed beside them already express.
+ *
+ * Pure, and driven directly by the suite for the four shapes the corpus does not contain
+ * (a stubbed backend, project-wide notes, a clean export, and every group at once).
+ */
+export declare function nextSteps(data: ExportReportData): NextStep[];