@egildo/provenance 0.0.0-stage → 0.6.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egildo Tagliareni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img src="assets/logo.svg" alt="Provenance" width="360">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <strong>Every byte of rendered output, traced back to the exact file, version, and byte range that produced it.</strong>
+</p>
+
+<p align="center">
+  <img alt="version" src="https://img.shields.io/badge/version-0.5.0-blue">
+  <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="status" src="https://img.shields.io/badge/status-kernel%20%2B%20editing-orange">
+</p>
+
+---
+
+A rendered document is made of many files. By the time a page appears in a browser, it has read
+an include tree, a configuration cascade, stylesheets, fonts, images, and whatever plugins pulled
+in along the way. Two questions follow every render: **what did it actually load**, and **which
+files must change on disk** when someone edits what they see.
+
+Provenance is one structure that answers both. For a single rendered document, it knows every
+source involved, how those sources depend on each other, where each rendered thing came from, and
+how to stage and write changes back — without ever touching a filesystem itself.
+
+```ts
+import { openSession } from "@egildo/provenance";
+import { createNodeHost } from "@egildo/provenance/node";
+import { css } from "@egildo/provenance/css";
+import { html } from "@egildo/provenance/html";
+
+const session = await openSession({
+  host: createNodeHost(),
+  entry: "/path/to/index.html",
+  handlers: [html, css],
+});
+
+for (const source of session.sources()) {
+  console.log(source.id, source.state, source.location);
+}
+
+session.onChange(change => console.log(change));
+```
+
+## Why
+
+Most tools that need this answer it twice, with bookkeeping that can't talk to itself. BelType —
+the project Provenance was extracted from — kept a list of files read, a separate list of URLs
+loaded, two near-identical file watchers, and one hand-rolled rule mapping URLs back to files.
+Each piece answered one question. None of them could answer the other, because they shared no
+coordinates.
+
+Provenance gives every fact — an edge, a stamp, an edit — one coordinate system: a source, a
+version, and a byte range. Anything it knows can be joined against anything else it knows.
+
+## What it does
+
+- **Tracks sources of any kind.** Markdown, HTML, CSS, configuration, images, fonts — and
+  whatever a handler teaches it. Binary files are leaves: addressable, never parsed.
+- **Records dependencies twice.** *Declared* edges come from parsing; *observed* edges come from
+  what a runtime actually fetched. The two are kept apart on purpose — the gap between them is
+  the product, not noise to smooth over.
+- **Addresses rendered output.** Any rendered node can point back to the exact source, version,
+  and byte range that produced it.
+- **Stages edits.** Changes are held against a base version, previewed in memory, and written to
+  disk together. What gets written is exactly what the preview showed.
+
+It runs in any JavaScript realm — Node, a browser tab, a worker — because it performs **no I/O of
+its own**. Everything outside the call (reading, writing, watching, path arithmetic) is asked of a
+**host** the embedder supplies. A Node host ships as its own entry point; nothing else in the
+library imports from `node:`, and a test enforces that rather than trusting convention.
+
+## How it decides things
+
+Provenance is opinionated on purpose. Nine design principles govern it, each one stated as
+something it refuses to do:
+
+| Principle | Forbids |
+|---|---|
+| **One address space** | A fact with no address. A second coordinate system past the handler boundary. |
+| **Handlers declare; Provenance decides** | A handler that reads, resolves, caches, watches, or writes. |
+| **Derived facts are pure functions of versions** | Any `invalidate()` call, anywhere. A cache hit that skips re-registering its probes. |
+| **Declared and observed stay apart** | An observation that overwrites a declared edge. A disagreement smoothed away. |
+| **Source is the stored reality; renders are projections** | Writing Provenance's own bookkeeping into a source file. |
+| **Nothing touches disk before commit** | Any write outside commit. A staged edit expressed against another staged edit's result. |
+| **Edits are splices** | A printer or serializer that regenerates a source from a tree. |
+| **Languages are plugins; nesting is delegation** | Language knowledge in the core. A handler parsing another language's region itself. |
+| **Supply, not meaning** | A `node:` import outside the Node host. A host that returns a verdict instead of a fact. |
+
+The full reasoning — with the incidents each rule was cut from — is in
+[the design principles](docs/principles.md).
+
+## Status
+
+**The kernel is built, and editing's first slice. Observation is not.**
+
+A session finds every source reachable from an entry document and its roots, records each
+declared dependency against the exact bytes that asked for it, keeps broken references visible
+until they heal, and reports what changed as files change. See
+[the kernel spec](specs/source-graph-kernel/spec.md) for exactly what that covers, and
+[the changelog](CHANGELOG.md) for what shipped in each release.
+
+Since 0.5.0 it also **writes back**: a tool stages an edit to a value, sees a preview, and commits it;
+the edit lands in exactly the bytes of that value, every other byte untouched, and survives the
+file changing on disk in the meantime ([the design](docs/write-back.md),
+[the editing spec](specs/editing/spec.md)). Writing is granted, never ambient. Since 0.6.0 it
+also inserts and deletes entries ([insert-delete](specs/insert-delete/spec.md)), and an edit staged on a file that a
+colleague is mid-way through saving waits for it to parse again. Format plug-ins come from outside —
+Cascata's YAML and JSON writers are the first.
+
+What's next: **stamps** (outputs that carry their source address, so an edit on a rendered page
+finds its way back), **Markdown units** and a **CSS writer**, then **observation** — see
+[the vision's "What arrives first"](docs/vision.md#what-arrives-first).
+
+## Install
+
+```bash
+npm install @egildo/provenance
+```
+
+Its tests prove write-back end to end with Cascata, a development dependency, `@egildo/cascata`.
+
+Requires Node 22 or later (22.18+ to run the tests from source, for type stripping).
+
+## Entry points
+
+| Import | What it gives you |
+|---|---|
+| `@egildo/provenance` | `openSession` and the core types |
+| `@egildo/provenance/html` | An HTML handler, on [parse5](https://github.com/inikulin/parse5) |
+| `@egildo/provenance/css` | A CSS handler, on [PostCSS](https://postcss.org/) |
+| `@egildo/provenance/node` | The Node host |
+| `@egildo/provenance/memory` | An in-memory host, for any realm — tests, browsers, workers |
+
+Every export is listed in [the public API contract](specs/source-graph-kernel/contracts/public-api.md).
+
+## Who it's for
+
+- **BelType**, first — replacing its file list, URL list, two watchers, and eventually its
+  editing server's write path.
+- **Cascata**, by shape and not by import — a read pass's host satisfies Cascata's `Host`
+  interface structurally, so Cascata's configuration files become session roots without Cascata
+  ever importing Provenance.
+- **The CSS tools**, which build on Provenance's addresses and its edit model.
+- **Any tool** that renders documents from files and needs to know what it read, what the runtime
+  loaded, and how to write back.
+
+What it deliberately stays out of — rendering, transforming, reading meaning, serving, history —
+is in [the vision's "What it is not"](docs/vision.md#what-it-is-not), each exclusion argued for.
+
+## Documentation
+
+- **[Vision](docs/vision.md)** — what Provenance is for, who it serves, what it refuses to be.
+- **[Design principles](docs/principles.md)** — how it decides things, each rule with what it forbids.
+- **[Glossary](docs/glossary.md)** — every christened term, and which meaning of "provenance" is ours.
+- **[Design synthesis](docs/design-synthesis.md)** — the day-zero design the vision was drawn from.
+- **[Kernel spec](specs/source-graph-kernel/spec.md)** and **[read-passes spec](specs/read-passes/spec.md)** — what's built, precisely.
+
+## Development
+
+```bash
+npm test    # type-checks and runs the tests
+npm run build   # writes dist/
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/css.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from "./index.ts";
+export declare const css: Handler;

package/dist/css.js

@@ -0,0 +1,77 @@
+// The CSS handler: `url()`, `image-set()` strings and `@import`, found with PostCSS
+// (specs/source-graph-kernel/research.md, CSS handler). Embedded regions are not its concern.
+import safeParse from "postcss-safe-parser";
+import valueParser from "postcss-value-parser";
+/** Undoes CSS escapes: `\` and one to six hex digits (and one following space), or `\` and a character. */
+function unescape(text) {
+    return text.replace(/\\(?:([0-9a-f]{1,6})[ \t\n]?|([^\n]))/gi, (_, hex, char) => hex ? String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff) || 0xfffd) : (char ?? ""));
+}
+/** The request a `url()` argument or a string holds, with its range in the whole text. */
+function literal(node, offset, kind) {
+    if (node.type === "word") {
+        return { start: offset + node.sourceIndex, end: offset + node.sourceEndIndex, request: unescape(node.value), kind };
+    }
+    if (node.type === "string") {
+        const end = node.unclosed ? node.sourceEndIndex : node.sourceEndIndex - 1;
+        return { start: offset + node.sourceIndex + 1, end: offset + end, request: unescape(node.value), kind };
+    }
+    return undefined;
+}
+const isNamed = (node, ...names) => node.type === "function" && names.includes(node.value.toLowerCase());
+/** Every `url()`, and every string directly inside `image-set()`, in a value placed at `offset`. */
+function urls(value, offset, requests) {
+    valueParser(value).walk(node => {
+        if (node.type !== "function")
+            return;
+        if (isNamed(node, "url")) {
+            const found = node.nodes[0] && literal(node.nodes[0], offset, "candidate");
+            if (found)
+                requests.push(found);
+            return false;
+        }
+        if (isNamed(node, "image-set", "-webkit-image-set")) {
+            for (const child of node.nodes) {
+                const found = child.type === "string" && literal(child, offset, "candidate");
+                if (found)
+                    requests.push(found);
+            }
+        }
+        return undefined;
+    });
+}
+/** `@import`'s URL: required unless a condition (media, `supports()`) follows; a `layer` is not one. */
+function importRequest(params, offset) {
+    const nodes = valueParser(params).nodes.filter(n => n.type !== "space" && n.type !== "comment");
+    const [first, ...rest] = nodes;
+    if (!first)
+        return undefined;
+    const conditioned = rest.some(n => !(n.type === "word" && n.value.toLowerCase() === "layer") && !isNamed(n, "layer"));
+    const kind = conditioned ? "candidate" : "requires";
+    if (first.type === "string")
+        return literal(first, offset, kind);
+    if (isNamed(first, "url") && first.type === "function" && first.nodes[0])
+        return literal(first.nodes[0], offset, kind);
+    return undefined;
+}
+export const css = {
+    claims: location => location.toLowerCase().endsWith(".css"),
+    analyze(text) {
+        const requests = [];
+        safeParse(text).walk(node => {
+            const start = node.source?.start?.offset;
+            if (start === undefined)
+                return;
+            if (node.type === "decl") {
+                const value = node.raws.value?.raw ?? node.value;
+                urls(value, start + node.prop.length + (node.raws.between ?? "").length, requests);
+            }
+            else if (node.type === "atrule" && node.name.toLowerCase() === "import") {
+                const params = node.raws.params?.raw ?? node.params;
+                const found = importRequest(params, start + 1 + node.name.length + (node.raws.afterName ?? "").length);
+                if (found)
+                    requests.push(found);
+            }
+        });
+        return { requests };
+    },
+};

package/dist/html.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from "./index.ts";
+export declare const html: Handler;

package/dist/html.js

@@ -0,0 +1,128 @@
+// The HTML handler: the attributes that make a browser load something, found with parse5
+// (specs/source-graph-kernel/contracts/public-api.md, Handlers). `<style>` and `style="…"` are
+// CSS regions, not this handler's language, and wait for regions.
+import { parse } from "parse5";
+/** The value's range inside an attribute's `name="value"` span, or undefined for a bare name. */
+function valueRange(text, span) {
+    const raw = text.slice(span.startOffset, span.endOffset);
+    const head = /^[^\s=]+\s*=\s*(["']?)\s*/.exec(raw);
+    if (!head)
+        return undefined;
+    const quoted = head[1] !== "" && raw.endsWith(head[1]) && raw.length > head[0].length;
+    const value = raw.slice(head[0].length, raw.length - (quoted ? 1 : 0));
+    return { start: span.startOffset + head[0].length, end: span.startOffset + head[0].length + value.trimEnd().length };
+}
+/**
+ * The URL ranges in a `srcset`, per the HTML standard's "parse a srcset attribute": a URL is a
+ * run of non-whitespace; trailing commas end it; descriptors run to a comma outside parentheses.
+ */
+function srcsetUrls(value) {
+    const urls = [];
+    const space = /[\t\n\f\r ]/;
+    let i = 0;
+    while (i < value.length) {
+        while (i < value.length && (space.test(value[i]) || value[i] === ","))
+            i++;
+        if (i >= value.length)
+            break;
+        const start = i;
+        while (i < value.length && !space.test(value[i]))
+            i++;
+        let end = i;
+        if (value[end - 1] === ",") {
+            while (end > start && value[end - 1] === ",")
+                end--;
+        }
+        else {
+            let depth = 0;
+            while (i < value.length && !(value[i] === "," && depth === 0)) {
+                if (value[i] === "(")
+                    depth++;
+                else if (value[i] === ")" && depth > 0)
+                    depth--;
+                i++;
+            }
+        }
+        if (end > start)
+            urls.push({ start, end });
+    }
+    return urls;
+}
+/** Which attributes of an element load something, and how surely. */
+function loads(element) {
+    const attr = (name) => element.attrs.find(a => a.name === name && !a.prefix)?.value;
+    const lazy = attr("loading")?.toLowerCase() === "lazy";
+    switch (element.tagName) {
+        case "link": {
+            const rel = (attr("rel") ?? "").toLowerCase().split(/\s+/);
+            if (rel.includes("stylesheet")) {
+                return [["href", attr("media") !== undefined || rel.includes("alternate") ? "candidate" : "requires"]];
+            }
+            return ["icon", "preload", "modulepreload", "prefetch"].some(r => rel.includes(r)) ? [["href", "candidate"]] : [];
+        }
+        case "img":
+            return [["src", lazy ? "candidate" : "requires"], ["srcset", "candidate", true]];
+        case "iframe":
+            return [["src", lazy ? "candidate" : "requires"]];
+        case "source":
+            return [["src", "candidate"], ["srcset", "candidate", true]];
+        case "video":
+            return [["src", "candidate"], ["poster", "candidate"]];
+        case "audio":
+            return [["src", "candidate"]];
+        case "object":
+            return [["data", "requires"]];
+        case "script":
+            return [["src", "requires"]];
+        case "use":
+            return [["href", "requires"], ["xlink:href", "requires"]];
+        default:
+            return [];
+    }
+}
+export const html = {
+    claims: location => /\.html?$/i.test(location),
+    analyze(text) {
+        const requests = [];
+        let base;
+        const visit = (node) => {
+            if ("tagName" in node) {
+                if (node.tagName === "base" && base === undefined) {
+                    base = node.attrs.find(a => a.name === "href" && !a.prefix)?.value;
+                }
+                for (const [name, kind, isSrcset] of loads(node)) {
+                    const attribute = node.attrs.find(a => (a.prefix ? `${a.prefix}:${a.name}` : a.name) === name);
+                    const span = node.sourceCodeLocation?.attrs?.[name];
+                    const range = attribute && span && valueRange(text, span);
+                    if (!attribute || !range)
+                        continue;
+                    if (!isSrcset) {
+                        requests.push({ ...range, request: attribute.value.trim(), kind });
+                        continue;
+                    }
+                    // The ranges come from the text as written, the requests from the decoded value; they
+                    // pair up unless an entity changed where a comma or a space falls.
+                    const written = srcsetUrls(text.slice(range.start, range.end));
+                    const decoded = srcsetUrls(attribute.value);
+                    if (written.length !== decoded.length)
+                        continue;
+                    written.forEach((w, k) => {
+                        requests.push({
+                            start: range.start + w.start,
+                            end: range.start + w.end,
+                            request: attribute.value.slice(decoded[k].start, decoded[k].end),
+                            kind,
+                        });
+                    });
+                }
+            }
+            if ("childNodes" in node)
+                for (const child of node.childNodes)
+                    visit(child);
+            if ("content" in node)
+                visit(node.content);
+        };
+        visit(parse(text, { sourceCodeLocationInfo: true }));
+        return base === undefined ? { requests } : { requests, base };
+    },
+};