@mapled/cli 0.9.0 → 0.10.0

package/README.md

@@ -97,7 +97,7 @@ npx @mapled/cli scan
 npx @mapled/cli scan --write
 ```
 
-The scanner reads the site's source and writes down what it reads from Mapled: the pages (from the framework's file layout — Next.js App and Pages Router, Astro, SvelteKit, Nuxt, Remix) and one binding per place a collection or field is used.
+The scanner reads the site's source and writes down what it reads from Mapled: the pages (from the framework's file layout — Next.js App and Pages Router, Astro, SvelteKit, Nuxt, Remix — or a plain HTML site's `.html` files) and one binding per place a collection or field is used.
 
 ```text
 Scanned 42 files with TypeScript — 3 pages, 14 bindings.
@@ -113,6 +113,21 @@ No mapled/manifest.json yet — run `mapled scan --write` to create it, then `ma
 
 It follows `getRecords` / `getRecord` / `getRecordBySlug` / `getSingle` calls through variables, destructuring, `.map()` callbacks and into the components a record is passed to as a prop, and through helpers in `lib/` that return a read. The parser is your repository's own TypeScript; without it the scanner still finds the collections, but not the fields. Source code never leaves your machine — only the manifest does, when you push it.
 
+**A plain HTML site** (`framework` is `plain-html` in `mapled.json` — a folder with an `index.html` and no framework in `package.json`) has no reads in code: the scanner reads the `data-mapled-*` attributes of its `.html` files the way the [`@mapled/vanilla`](https://www.npmjs.com/package/@mapled/vanilla) script does, in the tree a browser builds from the file (the CLI carries the standard HTML parser, parse5, inside — nothing to install). Each file is a page where a static host serves it (`index.html` → `/`, `blog/index.html` → `/blog/`, `post.html` → `/post.html`, `public/` from the root); a record read by `data-mapled-slug-param` has its own address with that parameter in the query, so **Preview** in the record's editor opens the right page — and the scan says when Preview can't open an address. The target of a binding is what the attribute renders — `data-mapled-format="markdown"` rich text, an `<img>` an image, `data-mapled-bind-href` a link — and each different way a field is read is a binding of its own, so a field bound where it can't render shows up as a mismatch even when another element reads it well. With the schema at hand it also names the paths nothing in Mapled answers to: on the page, a misspelled field and an empty one look the same.
+
+```text
+Scanned 2 HTML files — 2 pages, 11 bindings.
+
+/                       index.html
+  home   headline, intro, tagline
+  posts  list • date, slug, title
+/post.html?slug=[slug]  post.html
+  home   headline
+  posts  by slug • body, title
+
+⚠ This path names nothing in the schema: home.tagline (index.html). A misspelled field empties its place on the page, a misspelled single leaves the page's own HTML.
+```
+
 `--write` creates or updates `mapled/manifest.json`. Bindings the scan can't see (written by your AI agent, or by hand) are kept and listed; `--prune` drops them. Commit the file.
 
 ## Validate and push the manifest

package/dist/commands.js

@@ -12,6 +12,7 @@ import { formatChecks, GLYPH, paint, summarize, useColor } from "./output.js";
 import { diffSchema, formatChanges, pinSchema, readPin, SCHEMA_FILE, summarizeChanges, writePin } from "./pin.js";
 import { checkMapledMd, MD_FILE, mergeMd } from "./md.js";
 import { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
+import { scanHtml } from "./scanHtml.js";
 import { generateTypes } from "./types.js";
 /** The OAuth client id for this API — registered once per machine, and
     again when the server no longer knows it. */
@@ -490,8 +491,8 @@ export async function scan(ctx, flags) {
         throw new CliError(`The scan needs the schema to name the fields — sign in with \`mapled auth login\` or run \`mapled schema pull\` first.`);
     }
     const framework = found.config.framework ?? (await dr.detectFramework(found.dir)) ?? null;
-    const ts = loadTypeScript(found.dir);
-    const result = await scanRepository(found.dir, { framework, schema, ts });
+    // a plain HTML site declares its reads in attributes, not in code
+    const result = framework === "plain-html" ? await scanHtml(found.dir, { schema }) : await scanRepository(found.dir, { framework, schema, ts: loadTypeScript(found.dir) });
     const existing = await loadManifest(found.dir);
     const merged = mergeManifest(existing?.manifest ?? null, result, { prune: Boolean(flags.prune) });
     if (flags.json) {
@@ -500,7 +501,7 @@ export async function scan(ctx, flags) {
             await writeManifestFile(found.dir, merged.manifest);
         return;
     }
-    ctx.out(`Scanned ${plural(result.files, "file")} with ${result.parser === "typescript" ? "TypeScript" : "the tokenizer"} — ${plural(result.pages.length, "page")}, ${plural(result.bindings.length, "binding")}.`);
+    ctx.out(`${result.parser === "html" ? `Scanned ${plural(result.files, "HTML file")}` : `Scanned ${plural(result.files, "file")} with ${result.parser === "typescript" ? "TypeScript" : "the tokenizer"}`} — ${plural(result.pages.length, "page")}, ${plural(result.bindings.length, "binding")}.`);
     if (result.bindings.length > 0) {
         ctx.out("");
         for (const line of describeScan(result, schema))

package/dist/html5.d.ts

@@ -0,0 +1,66 @@
+import { type Token, type TreeAdapter, type TreeAdapterTypeMap } from "parse5";
+/** The HTML parser of `mapled scan` for a plain HTML site: parse5, the
+    WHATWG parsing algorithm — the tree a browser builds, and the one
+    jsdom builds for the runtime's tests. Tag soup decides which scope a
+    binding lands in (a <p> a <div> closes, a table's foster parent, a
+    template an end tag can't leave), so the scan can't read a tree of its
+    own. build.mjs bundles parse5 (pinned) into dist/html5.js: the CLI
+    still installs without dependencies.
+
+    What a page can make the parser do is held linear in its size — a
+    page is the site's to write, and the scan reads up to 2 MB of it:
+    - open elements: at most MAX_OPEN (Guarded.onItemPush). Every start tag
+      looks down them for a scope; 100,000 unclosed <div>s cost minutes.
+    - a tag's attributes: a set of names (Guarded, _leaveAttrName). parse5
+      compared each new one with every earlier one — 64,000 on one <div>: 4 s.
+    - the tree: children in linked lists (`linked` below), every operation
+      O(1). parse5's own tree keeps arrays, and foster parenting (text
+      before a <table>: indexOf), the adoption agency (a misnested </b>:
+      splice from the front) and repeated <html>/<body> tags (every
+      attribute so far) walk them — 160,000 "a<br>" in a table: 11 s.
+    The worst page within the cap is the depth times its start tags. */
+/** How deep elements may be open at once — Chrome's own limit of the tree it builds. */
+export declare const MAX_OPEN = 512;
+export declare class TooDeep extends Error {
+}
+export type Html5Attr = Token.Attribute;
+/** A node of the tree: an element (tagName), text, a comment, a doctype,
+    the document or a template's content — children linked both ways. Its
+    fields are named as parse5's own tree names them; `childNodes` is made
+    when asked for (the parser never asks). */
+export declare class Html5Node {
+    readonly nodeName: string;
+    tagName?: string;
+    namespaceURI?: string;
+    attrs?: Html5Attr[];
+    /** a <template>'s content: what the page's author wrote inside it */
+    content?: Html5Node;
+    parentNode: Html5Node | null;
+    firstChild: Html5Node | null;
+    lastChild: Html5Node | null;
+    previousSibling: Html5Node | null;
+    nextSibling: Html5Node | null;
+    /** a text's */
+    value?: string;
+    /** a comment's */
+    data?: string;
+    /** a doctype's */
+    name?: string;
+    publicId?: string;
+    systemId?: string;
+    /** the document's */
+    mode?: string;
+    /** the names an <html> or <body> has, as repeated tags add to them */
+    names?: Set<string>;
+    location?: Token.ElementLocation | null;
+    constructor(nodeName: string, extra?: Partial<Html5Node>);
+    /** none on a text, a comment or a doctype, as in parse5's tree */
+    get childNodes(): Html5Node[] | undefined;
+}
+type Map_ = TreeAdapterTypeMap<Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node>;
+/** parse5's default tree adapter, method for method, on linked children. */
+export declare const linked: TreeAdapter<Map_>;
+/** The document, with scripting on — as the runtime sees it (a <noscript>
+    is text). Throws TooDeep past MAX_OPEN open elements. */
+export declare function parseDocument(text: string): Html5Node;
+export {};