@valancex/cli 0.0.0-stage → 0.11.0

package/dist/init.js

@@ -0,0 +1,185 @@
+// `vlx init`: a new application on disk. This file is the work (names, what the questions mean, the files written, the install); the interface that asks the questions is `ui/init.tsx`, and
+// answers can equally come from flags, so everything here takes plain answers and nothing here prints.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PROJECT_FILE, WEB_FILE } from "./config.js";
+export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+const PACKAGE = new URL("../", import.meta.url);
+const TEMPLATES = new URL("../templates/", import.meta.url);
+const own = () => JSON.parse(readFileSync(new URL("package.json", PACKAGE), "utf8"));
+/** The package name an application gets: lowercase, URL-safe. */
+export const packageName = (name) => {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[-._]+|[-._]+$/g, "");
+    return slug === "" ? "app" : slug;
+};
+/** A reason the name cannot be used, or `undefined`. The directory is checked separately (it may be a path). */
+export const nameProblem = (name) => {
+    if (name.trim() === "") {
+        return "the application needs a name";
+    }
+    // oxlint-disable-next-line no-control-regex -- control characters are exactly what is refused
+    if (/[\u0000-\u001f"\\]/.test(name)) {
+        return "the name cannot contain quotes, backslashes or control characters";
+    }
+    return undefined;
+};
+/** The directory a name is made in: the name itself, written as a path, resolved from `cwd`. `my-app`, `./my-app` and `../x/my-app` are the directory; `My App` becomes `my-app`. */
+export const directoryFor = (name, cwd) => {
+    const trimmed = name.trim();
+    return /[\\/]/.test(trimmed) || trimmed.startsWith(".") ? resolve(cwd, trimmed) : resolve(cwd, packageName(trimmed));
+};
+/** The title a name gives the site: a path's last part, as written. */
+export const titleOf = (name) => basename(name.trim().replace(/[\\/]+$/, "")) || name.trim();
+/** What is in the way of writing into `dir`: nothing (it is absent or empty), or a sentence. */
+export const directoryProblem = (dir) => {
+    if (!existsSync(dir)) {
+        return undefined;
+    }
+    const entries = readdirSync(dir).filter((each) => each !== ".git");
+    return entries.length === 0 ? undefined : `${dir} is not empty`;
+};
+/** Which package manager started this: from the user agent npm, pnpm, yarn and bun set for what they run (`npm create`, `pnpm dlx`); `npm` otherwise. */
+export const detectPackageManager = (env = process.env) => {
+    const name = (env["npm_config_user_agent"] ?? "").split("/")[0];
+    return PACKAGE_MANAGERS.find((each) => each === name) ?? "npm";
+};
+export const runCommand = (manager) => (manager === "npm" ? "npm run" : manager === "bun" ? "bun run" : manager);
+const inCheckout = () => (own().dependencies["@valancex/common"] ?? "").startsWith("workspace:");
+/** What `@valancex/cli` is in the new package.json. A published package is a range; run from a checkout of the repository, the package this command came from, by path (the only place it can be installed from). */
+export const cliSpec = (manager, given) => {
+    if (given !== undefined) {
+        return given;
+    }
+    const manifest = own();
+    // Installed from the registry, a dependency on a sibling is a range; in a checkout of the repository it is still `workspace:`, and the package can only be installed from where it is.
+    if (!inCheckout()) {
+        return `^${manifest.version}`;
+    }
+    const path = fileURLToPath(PACKAGE).replace(/[\\/]$/, "");
+    return `${manager === "pnpm" ? "link" : "file"}:${path}`;
+};
+/**
+ * What `@valancex/common` is in the new package.json: the range this package depends on once published; inside the workspace (where that is `workspace:*`) the sibling package, by path, like
+ * `cliSpec`.
+ */
+export const commonSpec = (manager) => {
+    if (!inCheckout()) {
+        return own().dependencies["@valancex/common"] ?? "*";
+    }
+    return `${manager === "pnpm" ? "link" : "file"}:${fileURLToPath(new URL("../common/", PACKAGE)).replace(/[\\/]$/, "")}`;
+};
+const mesh = () => own().dependencies["@valancex/mesh-compiler"] ?? "^0.11.0";
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const files = (dir, prefix = "") => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? files(new URL(`${entry.name}/`, dir), `${prefix}${entry.name}/`) : [`${prefix}${entry.name}`]);
+/** The name a template file has once written: npm drops `.gitignore` from a package, so it ships as `gitignore`. */
+const written = (name) => (name === "gitignore" ? ".gitignore" : name);
+/** Every file the answers make, without writing any. */
+export const plan = (answers) => {
+    const out = new Map();
+    const title = titleOf(answers.name);
+    const web = answers.targets.includes("web");
+    const hasBase = answers.web.base !== "" && answers.web.base !== "/";
+    const settings = [hasBase ? `base ${answers.web.base}` : "", answers.web.url !== "" ? `url ${answers.web.url}` : ""].filter((each) => each !== "");
+    const tokens = {
+        name: title,
+        run: runCommand(answers.packageManager),
+        web_note: web && settings.length > 0 ? `, and \`${WEB_FILE}\` says where the web site is served (${settings.join(", ")})` : "",
+    };
+    const fill = (text) => text.replace(/\{\{(\w+)\}\}/g, (match, key) => tokens[key] ?? match);
+    if (web) {
+        const root = new URL("web/", TEMPLATES);
+        for (const file of files(root)) {
+            out.set(written(file), fill(readFileSync(new URL(file, root), "utf8")));
+        }
+    }
+    out.set(PROJECT_FILE, json({ $schema: "./node_modules/@valancex/cli/schemas/valance.schema.json", version: 1, name: title }));
+    if (web && (hasBase || answers.web.url !== "")) {
+        out.set(WEB_FILE, json({
+            $schema: "./node_modules/@valancex/cli/schemas/valance.web.schema.json",
+            version: 1,
+            ...(hasBase ? { base: answers.web.base } : {}),
+            ...(answers.web.url !== "" ? { url: answers.web.url } : {}),
+        }));
+    }
+    out.set("package.json", json({
+        name: packageName(basename(answers.dir)),
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        scripts: { dev: "vlx dev", build: "vlx build", check: "vlx check", typecheck: "vlx sync && tsc --noEmit", prepare: "vlx sync" },
+        dependencies: { "@valancex/common": commonSpec(answers.packageManager), effect: own().dependencies["effect"] ?? "^3.10.0" },
+        devDependencies: { "@types/node": "^22.0.0", "@valancex/cli": cliSpec(answers.packageManager, answers.cli), "@valancex/mesh-lsp": mesh(), typescript: "^5.6.0" },
+    }));
+    return { files: out };
+};
+/** Writes the application. Throws if the directory has something in it. Returns the files written, relative and sorted. */
+export const scaffold = (answers) => {
+    const problem = directoryProblem(answers.dir);
+    if (problem !== undefined) {
+        throw new Error(problem);
+    }
+    const { files: made } = plan(answers);
+    for (const [name, text] of made) {
+        const path = join(answers.dir, ...name.split("/"));
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+    }
+    return [...made.keys()].sort();
+};
+/** Runs `command args` in `cwd`, quietly. A `.cmd` shim on Windows needs a shell; nothing here takes user text as an argument. */
+export const run = (command, args, cwd) => new Promise((done) => {
+    const child = spawn(command, [...args], { cwd, stdio: ["ignore", "ignore", "pipe"], shell: process.platform === "win32" });
+    let output = "";
+    child.stderr.on("data", (chunk) => {
+        output = (output + chunk.toString()).slice(-4000);
+    });
+    child.on("error", (error) => {
+        done({ ok: false, output: error.message });
+    });
+    child.on("close", (code) => {
+        done({ ok: code === 0, output: output.trim().split("\n").slice(-6).join("\n") });
+    });
+});
+export const install = (answers) => run(answers.packageManager, ["install"], answers.dir);
+/** `git init` and a first commit's worth of staging is not ours to do: the repository is made, the author commits. */
+export const initGit = (dir) => run("git", ["init", "--quiet"], dir);
+/** Does everything the answers say, in order, and says how each step goes. Only writing the files can throw; an install or `git init` that fails is a note, not the end of the application. */
+export const execute = async (answers, report = () => undefined) => {
+    const notes = [];
+    report("files", "start");
+    const made = scaffold(answers);
+    report("files", "done", `${made.length} files`);
+    let installed = false;
+    let git = false;
+    if (answers.install) {
+        report("install", "start");
+        const ran = await install(answers);
+        installed = ran.ok;
+        report("install", ran.ok ? "done" : "failed", ran.ok ? undefined : ran.output);
+        if (!ran.ok) {
+            notes.push(`the dependencies were not installed (${answers.packageManager} install failed); run it yourself in the new directory`);
+        }
+    }
+    else {
+        report("install", "skipped");
+    }
+    if (answers.git) {
+        report("git", "start");
+        const ran = await initGit(answers.dir);
+        git = ran.ok;
+        report("git", ran.ok ? "done" : "failed", ran.ok ? undefined : ran.output);
+        if (!ran.ok) {
+            notes.push("no git repository was made (git init failed)");
+        }
+    }
+    else {
+        report("git", "skipped");
+    }
+    return { files: made, installed, git, notes };
+};

package/dist/markdown.d.ts

@@ -0,0 +1,20 @@
+import type { Block, Heading, Span } from "@valancex/common/internal";
+export interface LinkRef {
+    readonly href: string;
+    readonly line: number;
+    readonly image: boolean;
+}
+export interface Parsed {
+    readonly blocks: ReadonlyArray<Block>;
+    readonly outline: ReadonlyArray<Heading>;
+    /** Every link and image address, for the checks that need the other pages. */
+    readonly links: ReadonlyArray<LinkRef>;
+    /** The anchors of the page's headings. */
+    readonly anchors: ReadonlySet<string>;
+}
+export declare const slug: (text: string) => string;
+export declare const plain: (spans: ReadonlyArray<Span>) => string;
+/**
+ * Parses `text`. `file` and `offset` (the lines before `text` in the file, the front matter) only make diagnostics point at the right line.
+ */
+export declare const parseMarkdown: (text: string, file: string, offset: number) => Parsed;

package/dist/markdown.js

@@ -0,0 +1,185 @@
+import { AppError, diagnostic } from "./diagnostics.js";
+export const slug = (text) => text
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+const MARKS = /\*\*([^*]+)\*\*|`([^`]+)`|!\[[^\]]*\]\([^)\s]*\)|\[([^\]]+)\]\(([^)\s]+)\)|\*([^*\s][^*]*)\*|(?<![\w])_([^_\s][^_]*)_(?![\w])/g;
+const empty = { level: 0, anchor: "", spans: [], items: [], ordered: false, lang: "", text: "", src: "", alt: "" };
+export const plain = (spans) => spans.map((span) => span.text).join("");
+/**
+ * Parses `text`. `file` and `offset` (the lines before `text` in the file, the front matter) only make diagnostics point at the right line.
+ */
+export const parseMarkdown = (text, file, offset) => {
+    const lines = text.split("\n");
+    const blocks = [];
+    const links = [];
+    const problems = [];
+    const anchors = new Set();
+    const fail = (at, code, message) => {
+        problems.push(diagnostic(file, offset + at + 1, code, message));
+    };
+    const inline = (source, blockId, at) => {
+        const spans = [];
+        const add = (kind, value, href = "") => {
+            if (value !== "") {
+                spans.push({ id: `${blockId}.${spans.length}`, kind, text: value, href });
+            }
+        };
+        let from = 0;
+        for (let found = MARKS.exec(source); found !== null; found = MARKS.exec(source)) {
+            add("text", source.slice(from, found.index));
+            if (found[1] !== undefined) {
+                add("strong", found[1]);
+            }
+            else if (found[2] !== undefined) {
+                add("code", found[2]);
+            }
+            else if (found[3] !== undefined) {
+                add("link", found[3], found[4]);
+                links.push({ href: found[4], line: offset + at + 1, image: false });
+            }
+            else if (found[5] !== undefined || found[6] !== undefined) {
+                add("emphasis", found[5] ?? found[6]);
+            }
+            else {
+                fail(at, "md-inline-image", "an image must be on a line of its own");
+            }
+            from = found.index + found[0].length;
+        }
+        add("text", source.slice(from));
+        MARKS.lastIndex = 0;
+        return spans;
+    };
+    const next = () => `b${blocks.length}`;
+    let at = 0;
+    while (at < lines.length) {
+        const line = lines[at];
+        if (line.trim() === "") {
+            at += 1;
+            continue;
+        }
+        const fence = /^```\s*([\w+-]*)\s*$/.exec(line);
+        if (fence !== null) {
+            const start = at;
+            const body = [];
+            at += 1;
+            while (at < lines.length && !/^```\s*$/.test(lines[at])) {
+                body.push(lines[at]);
+                at += 1;
+            }
+            if (at >= lines.length) {
+                fail(start, "md-unclosed-fence", "this code fence is never closed");
+                break;
+            }
+            blocks.push({ ...empty, id: next(), kind: "code", lang: fence[1], text: body.join("\n") });
+            at += 1;
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
+        if (heading !== null) {
+            const level = heading[1].length;
+            const id = next();
+            if (level > 3) {
+                fail(at, "md-heading-level", "headings go from # to ###");
+                at += 1;
+                continue;
+            }
+            const spans = inline(heading[2], id, at);
+            const base = slug(plain(spans)) || "section";
+            let anchor = base;
+            for (let n = 2; anchors.has(anchor); n += 1) {
+                anchor = `${base}-${n}`;
+            }
+            anchors.add(anchor);
+            blocks.push({ ...empty, id, kind: "heading", level, anchor, spans });
+            at += 1;
+            continue;
+        }
+        const image = /^!\[([^\]]*)\]\(([^)\s]+)\)\s*$/.exec(line);
+        if (image !== null) {
+            blocks.push({ ...empty, id: next(), kind: "image", alt: image[1], src: image[2] });
+            links.push({ href: image[2], line: offset + at + 1, image: true });
+            at += 1;
+            continue;
+        }
+        if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
+            const id = next();
+            const ordered = /^\s*\d+\./.test(line);
+            const items = [];
+            while (at < lines.length && lines[at].trim() !== "") {
+                const item = /^(\s*)([-*]|\d+\.)\s+(.*\S)\s*$/.exec(lines[at]);
+                if (item !== null) {
+                    if (item[1] !== "") {
+                        fail(at, "md-nested-list", "lists nest one level at most: this build draws a single level");
+                    }
+                    else if (/\d/.test(item[2]) !== ordered) {
+                        fail(at, "md-mixed-list", "a list is either bulleted or numbered, not both");
+                    }
+                    items.push({ id: `${id}.i${items.length}`, spans: inline(item[3], `${id}.i${items.length}`, at) });
+                }
+                else if (/^\s+\S/.test(lines[at]) && items.length > 0) {
+                    const last = items[items.length - 1];
+                    const more = inline(lines[at].trim(), last.id, at);
+                    items[items.length - 1] = {
+                        id: last.id,
+                        spans: [
+                            ...last.spans,
+                            { id: `${last.id}.c${last.spans.length}`, kind: "text", text: " ", href: "" },
+                            ...more.map((span, n) => ({ ...span, id: `${last.id}.c${last.spans.length + n + 1}` })),
+                        ],
+                    };
+                }
+                else {
+                    break;
+                }
+                at += 1;
+            }
+            blocks.push({ ...empty, id, kind: "list", ordered, items });
+            continue;
+        }
+        if (line.startsWith(">")) {
+            const id = next();
+            const body = [];
+            const first = at;
+            while (at < lines.length && lines[at].startsWith(">")) {
+                body.push(lines[at].replace(/^>\s?/, ""));
+                at += 1;
+            }
+            blocks.push({ ...empty, id, kind: "quote", spans: inline(body.join(" ").trim(), id, first) });
+            continue;
+        }
+        if (/^\s*</.test(line)) {
+            fail(at, "md-html", "raw HTML is not supported: use Markdown, or a component in your layout");
+            at += 1;
+            continue;
+        }
+        if (/^\s*\|/.test(line)) {
+            fail(at, "md-table", "tables are not supported yet");
+            at += 1;
+            continue;
+        }
+        if (/^(-{3,}|\*{3,}|_{3,}|={3,})\s*$/.test(line)) {
+            fail(at, "md-rule", "horizontal rules and setext headings are not supported: use # headings");
+            at += 1;
+            continue;
+        }
+        const id = next();
+        const first = at;
+        const body = [line.trim()];
+        at += 1;
+        while (at < lines.length && lines[at].trim() !== "" && !/^(#{1,6}\s|```|>|\s*([-*]|\d+\.)\s|!\[)/.test(lines[at])) {
+            body.push(lines[at].trim());
+            at += 1;
+        }
+        blocks.push({ ...empty, id, kind: "paragraph", spans: inline(body.join(" "), id, first) });
+    }
+    if (problems.length > 0) {
+        throw new AppError(problems);
+    }
+    const outline = blocks
+        .filter((block) => block.kind === "heading" && block.level >= 2)
+        .map((block) => ({ id: block.id, label: plain(block.spans), anchor: block.anchor, level: block.level }));
+    return { blocks, outline, links, anchors };
+};

package/dist/node.d.ts

@@ -0,0 +1,10 @@
+export { build } from "./build.js";
+export type { Built } from "./build.js";
+export { check } from "./check.js";
+export type { Checked } from "./check.js";
+export { findRoot, loadConfig } from "./config.js";
+export type { Config } from "./config.js";
+export { dev } from "./dev.js";
+export type { Dev, DevOptions } from "./dev.js";
+export { AppError, format } from "./diagnostics.js";
+export type { Diagnostic } from "./diagnostics.js";

package/dist/node.js

@@ -0,0 +1,6 @@
+// The tooling as a library: what the `valance` command runs, for tests, scripts and other tools. Node only.
+export { build } from "./build.js";
+export { check } from "./check.js";
+export { findRoot, loadConfig } from "./config.js";
+export { dev } from "./dev.js";
+export { AppError, format } from "./diagnostics.js";

package/dist/outline.d.ts

@@ -0,0 +1,17 @@
+export interface TagUse {
+    /** The tag, as written: `theme-toggle`, `button`, `mesh-slot`. */
+    readonly name: string;
+    /** Where the `<` is, from the start of the source. */
+    readonly offset: number;
+}
+export interface Outline {
+    /** Every element written, in order, repeats included. */
+    readonly tags: ReadonlyArray<TagUse>;
+    /** The names of the slots the template places (`""` is the default slot). */
+    readonly slots: ReadonlyArray<string>;
+    /** The slots its elements fill (`<mesh-fill slot="footer">`). */
+    readonly fills: ReadonlyArray<string>;
+}
+export declare const outline: (source: string) => Outline;
+/** The distinct tag names a template writes, with the offset of the first. */
+export declare const tagsOf: (source: string) => ReadonlyMap<string, number>;

package/dist/outline.js

@@ -0,0 +1,88 @@
+// A read-only outline of a template's source: the tags it writes, and the slots it places and fills. It is a scanner, not the MESH parser: it knows only where an element starts, which is enough to
+// answer "which components does this template use" without compiling it (the compile needs the answer to build the model it compiles against). Expressions in `{…}`, quoted values and comments
+// are skipped, so `{a <b}` or `title="<x>"` is never read as a tag.
+//
+// MESH owns the language, and a parser in its package is where this belongs; until that exists, this is the one place in VALANCE that looks inside a template's text.
+const NAME = /[a-z][a-z0-9-]*/y;
+const LITERAL = (attribute) => new RegExp(`${attribute}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`);
+/** The offset just past the `}` that closes the `{` at `open`; strings inside are respected. */
+const afterBrace = (source, open) => {
+    let depth = 0;
+    for (let at = open; at < source.length; at += 1) {
+        const char = source[at];
+        if (char === '"' || char === "'" || char === "`") {
+            at += 1;
+            while (at < source.length && source[at] !== char) {
+                at += source[at] === "\\" ? 2 : 1;
+            }
+        }
+        else if (char === "{") {
+            depth += 1;
+        }
+        else if (char === "}" && --depth === 0) {
+            return at + 1;
+        }
+    }
+    return source.length;
+};
+/** The offset of the `>` that ends the start tag whose attributes begin at `from` (quotes and `{…}` respected), or the end of the source. */
+const endOfTag = (source, from) => {
+    for (let at = from; at < source.length; at += 1) {
+        const char = source[at];
+        if (char === '"' || char === "'") {
+            at = source.indexOf(char, at + 1);
+            if (at < 0) {
+                return source.length;
+            }
+        }
+        else if (char === "{") {
+            at = afterBrace(source, at) - 1;
+        }
+        else if (char === ">") {
+            return at;
+        }
+    }
+    return source.length;
+};
+export const outline = (source) => {
+    const tags = [];
+    const slots = [];
+    const fills = [];
+    for (let at = 0; at < source.length; at += 1) {
+        const char = source[at];
+        if (char === "{") {
+            at = afterBrace(source, at) - 1;
+        }
+        else if (char === "<" && source.startsWith("<!--", at)) {
+            const end = source.indexOf("-->", at + 4);
+            at = end < 0 ? source.length : end + 2;
+        }
+        else if (char === "<") {
+            NAME.lastIndex = at + 1;
+            const name = NAME.exec(source)?.[0];
+            if (name === undefined) {
+                continue;
+            }
+            const end = endOfTag(source, at + 1 + name.length);
+            const start = source.slice(at, end);
+            tags.push({ name, offset: at });
+            if (name === "mesh-slot" || name === "mesh-fill") {
+                const attribute = LITERAL(name === "mesh-slot" ? "name" : "slot").exec(start);
+                (name === "mesh-slot" ? slots : fills).push(attribute?.[1] ?? attribute?.[2] ?? "");
+            }
+            // Past the tag's name: its attributes may hold `{…}`, which the next turn of the loop skips, but a `<` in a quoted value is not an element.
+            at = Math.max(at, end - 1);
+        }
+    }
+    return { tags, slots, fills };
+};
+/** The distinct tag names a template writes, with the offset of the first. */
+export const tagsOf = (source) => {
+    const first = new Map();
+    for (const tag of outline(source).tags) {
+        if (!first.has(tag.name)) {
+            first.set(tag.name, tag.offset);
+        }
+    }
+    return first;
+};

package/dist/project.d.ts

@@ -0,0 +1,8 @@
+export declare const GENERATED_DIR = ".valance";
+export declare const OUTPUT_DIR = "dist";
+export declare const ENTRY_FILE = "src/main.ts";
+export declare const generated: (root: string, name: string) => string;
+/** Writes `text` unless the file already says exactly that: a watcher that sees a write should only see a change. Returns whether it wrote. */
+export declare const writeIfChanged: (path: string, text: string) => boolean;
+/** Keeps `.valance/` out of version control without asking the author to remember: a `.gitignore` inside it. */
+export declare const ensureGeneratedDir: (root: string) => void;

package/dist/project.js

@@ -0,0 +1,20 @@
+// Where things are in a project. Authored: `valance.json`, `valance.web.json`, `content/`, `public/`, `src/`. Generated and never edited or committed: `.valance/`. The final site: `dist/`.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const GENERATED_DIR = ".valance";
+export const OUTPUT_DIR = "dist";
+export const ENTRY_FILE = "src/main.ts";
+export const generated = (root, name) => join(root, GENERATED_DIR, name);
+/** Writes `text` unless the file already says exactly that: a watcher that sees a write should only see a change. Returns whether it wrote. */
+export const writeIfChanged = (path, text) => {
+    if (existsSync(path) && readFileSync(path, "utf8") === text) {
+        return false;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    return true;
+};
+/** Keeps `.valance/` out of version control without asking the author to remember: a `.gitignore` inside it. */
+export const ensureGeneratedDir = (root) => {
+    writeIfChanged(generated(root, ".gitignore"), "# Generated by `valance`. Never edited, never committed.\n*\n");
+};

package/dist/targets.d.ts

@@ -0,0 +1,9 @@
+export interface Target {
+    /** The flag (`--web`) and the name in `valance.<id>.json`. */
+    readonly id: "web";
+    readonly label: string;
+    readonly hint: string;
+}
+export declare const TARGETS: ReadonlyArray<Target>;
+export type TargetId = Target["id"];
+export declare const isTarget: (name: string) => name is TargetId;

package/dist/targets.js

@@ -0,0 +1,2 @@
+export const TARGETS = [{ id: "web", label: "Web", hint: "a website: Markdown pages and templates, built to a static site (settings in valance.web.json)" }];
+export const isTarget = (name) => TARGETS.some((each) => each.id === name);

package/dist/tree.d.ts

@@ -0,0 +1,47 @@
+import type { Schema } from "effect";
+import type { Component } from "@valancex/common";
+export interface Place {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface Node {
+    /** The tag: the template's file name without `.mprx`. */
+    readonly name: string;
+    /** The template, relative to the project. */
+    readonly file: string;
+    /** The interface the component declares: present when it declares one (an omitted side is none), absent when its contract is inferred from the template and where it is used. */
+    readonly interface?: {
+        readonly props: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+        readonly events: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+    };
+    /** The declared components its template writes. */
+    readonly uses: ReadonlyArray<string>;
+    /** Who uses it: the components whose templates write its tag; `"(application)"` for the layout and for an override. */
+    readonly parents: ReadonlyArray<string>;
+}
+export declare const APPLICATION = "(application)";
+export declare const nameOf: (file: string) => string;
+/** Every component the definition declares, once each by name: `layout`, each `override`, then each of `components`. Who uses whom is read from the templates (`linked`). */
+export declare const treeOf: (layout: Component | undefined, overrides: ReadonlyArray<Component>, components?: ReadonlyArray<Component>) => ReadonlyArray<Node>;
+/**
+ * The tree with who uses whom filled in: `usesOf` gives the tags each component's template writes. A component uses the declared components its template writes (not itself); the layout and each
+ * override are also the application's.
+ */
+export declare const linked: (nodes: ReadonlyArray<Node>, layout: Component | undefined, overrides: ReadonlyArray<Component>, usesOf: (name: string) => ReadonlyArray<string>) => ReadonlyArray<Node>;
+export declare const placeIn: (text: string, offset: number, file: string) => Place;
+export interface Site {
+    /** The file the site is in, relative to the project. */
+    readonly file: string;
+    /** The `import x from "./the.mprx"` line. */
+    readonly imported?: Place;
+    /** The `component(x, …)` call that defines the component. */
+    readonly call?: Place;
+    /** Where a prop or an event is declared in that call: its key in `props: { … }` or `events: { … }`. */
+    readonly member: (kind: "props" | "events", name: string) => Place | undefined;
+}
+/**
+ * Where each template's component is defined: the `component(template, …)` call in the project's TypeScript, wherever it is written (the entry file, or a file of its own beside the template), and the
+ * keys of its contract. A text search for pointing, not a parse: what it cannot find it leaves out, and callers fall back to the template.
+ */
+export declare const declarationsOf: (root: string) => ReadonlyMap<string, Site>;