@jxsuite/schema 5.3.0 → 5.5.0

package/package.json

@@ -66,7 +66,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/src/guards.ts

@@ -242,7 +242,120 @@ export function isTemplateString(value?: unknown): value is string {
  * because a newline after `return` is an ASI bare return.
  */
 export function bodyReturnsValue(body: string): boolean {
-  return /\breturn\b[^\S\n]*(?![;}\s]|$)/.test(body);
+  return /\breturn\b[^\S\n]*(?![;}\s]|$)/.test(maskCode(body));
+}
+
+/**
+ * A function body with its comments and the contents of its strings blanked, so a pattern reads
+ * only code (`spec.md` §23.1). The result is the same length, every newline kept, so an offset in
+ * it is an offset in the body. A string keeps its quotes, so `return "x"` still returns a value,
+ * and a template literal's `${…}` keeps its contents, which are code.
+ *
+ * A scanner and not a parser, because the interpreter must answer the same way and cannot carry
+ * one. Its known limit: a regular expression literal is read as code, so a quote inside one can
+ * blank what follows it.
+ *
+ * @param body The body, already JavaScript.
+ */
+export function maskCode(body: string): string {
+  // Nothing can open a comment or a string: the body is all code, and most handlers are.
+  if (!/[/'"`]/u.test(body)) {
+    return body;
+  }
+  const known = masked.get(body);
+  if (known !== undefined) {
+    return known;
+  }
+  const result = scanCode(body);
+  if (masked.size >= MASKED_LIMIT) {
+    masked.clear();
+  }
+  masked.set(body, result);
+  return result;
+}
+
+/**
+ * Bodies already masked. Every pattern a compile runs over a body reads it masked, and a dev server
+ * compiles the same bodies again on every change, so the scan is done once per text. Bounded,
+ * because a long session sees many texts.
+ */
+const masked = new Map<string, string>();
+const MASKED_LIMIT = 2048;
+
+/** The scan {@link maskCode} caches. */
+function scanCode(body: string): string {
+  /* UTF-16 units, as `at` counts them. Code points (`[...body]`) made an astral character in a
+     string one element for two offsets, so the result came back short and every offset after it,
+     which is what a caller splices the body at, was off by one. */
+  const out = body.split("");
+  const blank = (at: number): void => {
+    if (out[at] !== undefined && out[at] !== "\n") {
+      out[at] = " ";
+    }
+  };
+  /** The brace depth of each template substitution still open, innermost last. */
+  const substitutions: number[] = [];
+  let inTemplate = false;
+  let at = 0;
+  while (at < body.length) {
+    const char = body.charAt(at);
+    if (inTemplate) {
+      if (char === "\\") {
+        blank(at);
+        blank(at + 1);
+        at += 2;
+      } else if (char === "`") {
+        inTemplate = false;
+        at += 1;
+      } else if (char === "$" && body.charAt(at + 1) === "{") {
+        substitutions.push(0);
+        inTemplate = false;
+        at += 2;
+      } else {
+        blank(at);
+        at += 1;
+      }
+    } else if (char === "/" && body.charAt(at + 1) === "/") {
+      while (at < body.length && body.charAt(at) !== "\n") {
+        blank(at);
+        at += 1;
+      }
+    } else if (char === "/" && body.charAt(at + 1) === "*") {
+      const end = body.indexOf("*/", at + 2);
+      const stop = end === -1 ? body.length : end + 2;
+      for (; at < stop; at += 1) {
+        blank(at);
+      }
+    } else if (char === "'" || char === '"') {
+      at += 1;
+      while (at < body.length && body.charAt(at) !== char && body.charAt(at) !== "\n") {
+        if (body.charAt(at) === "\\") {
+          blank(at);
+          at += 1;
+        }
+        blank(at);
+        at += 1;
+      }
+      at += 1;
+    } else if (char === "`") {
+      inTemplate = true;
+      at += 1;
+    } else {
+      const open = substitutions.length - 1;
+      if (open >= 0 && char === "{") {
+        substitutions[open] = (substitutions[open] ?? 0) + 1;
+      } else if (open >= 0 && char === "}") {
+        if (substitutions[open] === 0) {
+          substitutions.pop();
+          inTemplate = true;
+        } else {
+          substitutions[open] = (substitutions[open] ?? 1) - 1;
+        }
+      }
+      at += 1;
+    }
+  }
+  return out.join("");
 }
 
 // ─── Style guards & accessors ───────────────────────────────────────────────────

package/src/jxn/index.ts

@@ -12,7 +12,8 @@ export { JxnError } from "./errors.ts";
 export type { JxnSpan } from "./errors.ts";
 export { countJxnComments, lintJxn } from "./lint.ts";
 export type { JxnWarning } from "./lint.ts";
-export { parseJxn, parseJxnWithSpans } from "./parse.ts";
+export { kdlProblem, parseJxn, parseJxnWithSpans } from "./parse.ts";
 export { reconcileJxn } from "./reconcile.ts";
 export type { JxnReader, JxnReading } from "./reconcile.ts";
 export { serializeJxn } from "./serialize.ts";
+export { parseProject, parseProjectWithSpans, serializeProject } from "./project.ts";

package/src/jxn/lint.ts

@@ -34,10 +34,16 @@ interface JxnScan {
   escapes: number[];
 }
 
+/**
+ * The `/- kdl-version 2` line a file may open with. It is a slashdash by spelling, but it says
+ * which KDL the file is written in and holds nothing `.json` would lose, so it is not counted.
+ */
+const VERSION_MARKER = /^\uFEFF?\s*\/-[^\S\n]*kdl-version[^\S\n]+\d+[^\S\n]*(?:\n|$)/u;
+
 /** Walk a file's text, knowing what is a string and what is a comment. */
 function scanJxn(text: string): JxnScan {
   const scan: JxnScan = { comments: 0, escapes: [] };
-  let index = 0;
+  let index = VERSION_MARKER.exec(text)?.[0].length ?? 0;
   while (index < text.length) {
     if (text.startsWith("//", index)) {
       scan.comments += 1;

package/src/jxn/parse.ts

@@ -28,14 +28,14 @@ const ANNOTATIONS = new Set(["array", "fn", "object", "on", "ref"]);
 const RESERVED_CHILDREN = new Set(["attributes", "script", "state", "style"]);
 
 /** What one read of a file is building. */
-interface Reader {
+export interface Reader {
   /** Where each thing came from, by JSON Pointer, when that was asked for. */
   spans: Map<string, JxnSpan> | null;
   text: string;
 }
 
 /** Set a key, refusing a repeat and a key that would be a prototype rather than data. */
-function setKey(
+export function setKey(
   target: JsonObject,
   key: string,
   value: JsonValue,
@@ -53,7 +53,7 @@ function setKey(
 }
 
 /** An error at a node or entry's place in the file. */
-function failure(reader: Reader, at: Entry | Node, message: string): JxnError {
+export function failure(reader: Reader, at: Entry | Node, message: string): JxnError {
   const start = spanOf(at)?.start;
   return new JxnError(message, start === undefined ? null : locate(reader.text, start));
 }
@@ -65,7 +65,7 @@ function spanOf(at: Entry | Node): JxnSpan | null {
 }
 
 /** Record where a pointer's value came from. */
-function mark(reader: Reader, pointer: string, at: Entry | Node): void {
+export function mark(reader: Reader, pointer: string, at: Entry | Node): void {
   const span = reader.spans ? spanOf(at) : null;
   if (span) {
     reader.spans?.set(pointer, span);
@@ -73,12 +73,12 @@ function mark(reader: Reader, pointer: string, at: Entry | Node): void {
 }
 
 /** A JSON Pointer token. */
-function token(key: string): string {
+export function token(key: string): string {
   return key.replaceAll("~", "~0").replaceAll("/", "~1");
 }
 
 /** A node's annotation, checked. */
-function annotationOf(reader: Reader, node: Node): string | null {
+export function annotationOf(reader: Reader, node: Node): string | null {
   const tag = node.getTag();
   if (tag !== null && !ANNOTATIONS.has(tag)) {
     throw failure(reader, node, `(${tag}) is not an annotation Jx Notation has`);
@@ -114,17 +114,17 @@ function valueOf(reader: Reader, entry: Entry): JsonValue {
 }
 
 /** A node's positional values, in order. */
-function positionals(reader: Reader, node: Node): JsonValue[] {
+export function positionals(reader: Reader, node: Node): JsonValue[] {
   return node.entries.filter((entry) => !entry.name).map((entry) => valueOf(reader, entry));
 }
 
 /** A node's named entries. */
-function properties(node: Node): Entry[] {
+export function properties(node: Node): Entry[] {
   return node.entries.filter((entry) => entry.name);
 }
 
 /** The node's children, or none. */
-function childrenOf(node: Node): readonly Node[] {
+export function childrenOf(node: Node): readonly Node[] {
   return node.children?.nodes ?? [];
 }
 
@@ -169,7 +169,7 @@ function readItems(reader: Reader, kids: readonly Node[], pointer: string): Json
 }
 
 /** A JSON block: JSON-in-KDL, plus `(ref)` and `(fn)`. */
-function readValue(reader: Reader, node: Node, pointer: string): JsonValue {
+export function readValue(reader: Reader, node: Node, pointer: string): JsonValue {
   const tag = annotationOf(reader, node);
   mark(reader, pointer, node);
   if (tag === "fn") {
@@ -217,7 +217,7 @@ function readValue(reader: Reader, node: Node, pointer: string): JsonValue {
 }
 
 /** A `style` block: scalars, and nested blocks, with source order significant. */
-function readStyle(reader: Reader, node: Node, pointer: string): JsonObject {
+export function readStyle(reader: Reader, node: Node, pointer: string): JsonObject {
   const style: JsonObject = {};
   mark(reader, pointer, node);
   if (positionals(reader, node).length > 0) {
@@ -480,7 +480,7 @@ function readElementChild(
  * @param reader The read.
  * @param node The `$head` node.
  */
-function readHead(reader: Reader, node: Node): JsonValue {
+export function readHead(reader: Reader, node: Node): JsonValue {
   return childrenOf(node).map((kid, index) => {
     const pointer = `/$head/${index}`;
     return kid.getName() === "-"
@@ -489,8 +489,25 @@ function readHead(reader: Reader, node: Node): JsonValue {
   });
 }
 
+/**
+ * Why a file is not KDL at all, or null when it is: the test for a file that is not Jx Notation
+ * before anything asks what it means (desktop.md §7.8). A file that parses here may still not be a
+ * valid document; that is `parseJxn`'s answer.
+ *
+ * @param text The file.
+ * @returns The reason with its line and column, or null.
+ */
+export function kdlProblem(text: string): string | null {
+  try {
+    parseSource(text);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 /** Parse KDL, and turn its error into ours. */
-function parseSource(text: string): Document {
+export function parseSource(text: string): Document {
   const control = RAW_CONTROL.exec(text);
   if (control) {
     throw new JxnError(

package/src/jxn/project.ts

@@ -0,0 +1,248 @@
+/**
+ * A project file in Jx Notation: `project.jxn` (`site-architecture.md` §2.3).
+ *
+ * The grammar is `spec.md` §22's, with a different top level. There is no root element, and every
+ * node is a member of the configuration. `$head` has element rows, `style` and `$media` have style
+ * rows, and everything else is a JSON block. So the `$ref`, duplicate-key, NFC and refusal rules
+ * are the document grammar's own, and a person who can write one can write the other.
+ *
+ * The file declares itself with a `project` node, the first after any `$` metadata, whose one
+ * optional value is the project's `name`. `classifyJxn` reads that node without parsing the file.
+ *
+ * @docs framework/concepts/jxn-files
+ */
+import type { Node } from "@bgotink/kdl";
+import type { JsonObject, JsonValue, ProjectConfig } from "../../types.ts";
+import { isJsonObject } from "../guards.ts";
+import { normalizeObject } from "../parse.ts";
+import { classifyJxn } from "./classify.ts";
+import { JxnError } from "./errors.ts";
+import type { JxnSpan } from "./errors.ts";
+import {
+  annotationOf,
+  childrenOf,
+  failure,
+  mark,
+  parseSource,
+  positionals,
+  properties,
+  readHead,
+  readStyle,
+  readValue,
+  setKey,
+  token,
+} from "./parse.ts";
+import type { Reader } from "./parse.ts";
+import { reconcileJxn } from "./reconcile.ts";
+import type { JxnReading } from "./reconcile.ts";
+import { INDENT, down, isRef, scalar, writeHeadBlock, writeName, writeValue } from "./serialize.ts";
+
+/** The node that makes a `.jxn` file a project's. */
+const PROJECT_NODE = "project";
+
+/** The members whose rows are style declarations, in source order. */
+const STYLE_MEMBERS = new Set(["$media", "style"]);
+
+/** Read the `project` node: the file's kind, and the project's name. */
+function readProjectNode(reader: Reader, node: Node, config: JsonObject): void {
+  if (annotationOf(reader, node) !== null) {
+    throw failure(reader, node, `"project" names the file's kind, and takes no annotation`);
+  }
+  const values = positionals(reader, node);
+  if (values.length > 1 || properties(node).length > 0 || childrenOf(node).length > 0) {
+    throw failure(reader, node, `"project" holds one value, the project's name, and nothing else`);
+  }
+  if (values[0] !== undefined) {
+    setKey(config, "name", values[0], reader, node);
+    mark(reader, "/name", node);
+  }
+}
+
+/** Read one top-level member. */
+function readMember(reader: Reader, node: Node, config: JsonObject): void {
+  const name = node.getName();
+  const pointer = `/${token(name)}`;
+  const isPlain = node.getTag() === null;
+  let value: JsonValue;
+  if (name === "$head" && isPlain) {
+    value = readHead(reader, node);
+    mark(reader, pointer, node);
+  } else if (STYLE_MEMBERS.has(name) && isPlain) {
+    value = readStyle(reader, node, pointer);
+  } else {
+    value = readValue(reader, node, pointer);
+  }
+  setKey(config, name, value, reader, node);
+}
+
+/** Read a whole project file. */
+function readProject(reader: Reader): ProjectConfig {
+  if (classifyJxn(reader.text) === "document") {
+    throw new JxnError(
+      `A project file declares itself: its first node, after any $ metadata, is project "<name>"`,
+    );
+  }
+  const source = parseSource(reader.text);
+  const config: JsonObject = {};
+  let declared = false;
+  for (const node of source.nodes) {
+    const name = node.getName();
+    if (name === PROJECT_NODE) {
+      if (declared) {
+        throw failure(reader, node, `"project" is written twice, and a file declares one project`);
+      }
+      readProjectNode(reader, node, config);
+      declared = true;
+    } else {
+      // `classifyJxn` has already said that nothing but `$` metadata comes before the declaration.
+      readMember(reader, node, config);
+    }
+  }
+  /* SAFETY: every ProjectConfig member is optional, so any object is a structurally admissible
+     config; member-level checking is `validateProject`'s job, as it is for `project.json`. */
+  return normalizeObject(config) as ProjectConfig;
+}
+
+/**
+ * Read a `project.jxn` file.
+ *
+ * @param text The file.
+ * @param path Its path, when an error should name it.
+ * @returns The same `ProjectConfig` its `project.json` spelling reads to.
+ * @throws {JxnError} When it is not one, naming the line and column where it can.
+ */
+export function parseProject(text: string, path?: string): ProjectConfig {
+  try {
+    return readProject({ spans: null, text });
+  } catch (error) {
+    throw path !== undefined && error instanceof JxnError ? error.inFile(path) : error;
+  }
+}
+
+/**
+ * Read a `project.jxn` file, and where in the file each part of it came from.
+ *
+ * @param text The file.
+ * @throws {JxnError} When it is not one.
+ */
+export function parseProjectWithSpans(text: string) {
+  const spans = new Map<string, JxnSpan>();
+  return { config: readProject({ spans, text }), spans };
+}
+
+/**
+ * Style rows, one declaration per line, because `--="1280px"` on the node's own line reads badly
+ * and a project's tokens are what people scan.
+ */
+function writeStyleRows(key: string, style: JsonValue, indent: string, where: string): string[] {
+  if (!isJsonObject(style) || isRef(style)) {
+    throw new JxnError(`${where} is a set of declarations, and this is not one`);
+  }
+  const entries = Object.entries(style);
+  const head = indent + writeName(key, where);
+  if (entries.length === 0) {
+    return [`${head} {}`];
+  }
+  const inner = indent + INDENT;
+  const rows = entries.flatMap(([entry, value]) => {
+    const at = down(where, entry);
+    const spelled = scalar(value, inner, at);
+    if (spelled !== null) {
+      return [`${inner}${writeName(entry, at)} ${spelled}`];
+    }
+    return isJsonObject(value)
+      ? writeStyleRows(entry, value, inner, at)
+      : // A list, such as the several `@font-face` a stylesheet can hold, is the one other thing.
+        writeValue(entry, value, inner, at);
+  });
+  return [`${head} {`, ...rows, `${indent}}`];
+}
+
+/** One top-level member, in its canonical form. */
+function writeMember(key: string, value: JsonValue): string[] {
+  const where = down("", key);
+  if (key === "$head") {
+    return Array.isArray(value)
+      ? writeHeadBlock(value, INDENT)
+      : // Not a list, so not rows. The annotation is what stops it being read as them.
+        [`(object)${writeValue(key, value, "", where).join("\n")}`];
+  }
+  return STYLE_MEMBERS.has(key)
+    ? writeStyleRows(key, value, "", where)
+    : writeValue(key, value, "", where);
+}
+
+/** A project file in its canonical form. */
+function writeCanonical(config: ProjectConfig): string {
+  if (!isJsonObject(config)) {
+    throw new JxnError("A project's configuration is an object");
+  }
+  const source: JsonObject = config;
+  const header = ["/- kdl-version 2"];
+  const sections: string[][] = [];
+  const name = scalar(source.name, "", "/name");
+  for (const [key, value] of Object.entries(source)) {
+    if (key === "name" && name !== null) {
+      continue;
+    }
+    const isRows = key === "$head" || STYLE_MEMBERS.has(key);
+    const spelled = key.startsWith("$") && !isRows ? scalar(value, "", down("", key)) : null;
+    // Short metadata such as `$schema` stays above the declaration, where a document has it.
+    if (spelled === null || spelled.includes("\n")) {
+      sections.push(writeMember(key, value));
+    } else {
+      header.push(`${writeName(key, down("", key))} ${spelled}`);
+    }
+  }
+  header.push(name === null ? PROJECT_NODE : `${PROJECT_NODE} ${name}`);
+  return `${[header, ...sections].map((lines) => lines.join("\n")).join("\n\n")}\n`;
+}
+
+/** Read a file the way {@link reconcileJxn} wants to be told about it. */
+function readForReconcile(text: string): JxnReading {
+  const { config, spans } = parseProjectWithSpans(text);
+  return { document: isJsonObject(config) ? config : null, spans };
+}
+
+/**
+ * Write a project's configuration as a `project.jxn` file.
+ *
+ * @param config The configuration.
+ * @param previous The file it is replacing. Everything that still means the same keeps its exact
+ *   text, comments and blank lines included. Without one, the whole file is canonical.
+ * @throws {JxnError} When it holds what Jx Notation cannot spell, naming the JSON Pointer.
+ */
+export function serializeProject(config: ProjectConfig, previous?: string): string {
+  if (previous === undefined) {
+    return writeCanonical(config);
+  }
+  const canonical = writeCanonical(inOrderOf(config, previous));
+  return reconcileJxn(previous, canonical, readForReconcile);
+}
+
+/**
+ * The configuration with its members in the order the previous file has them.
+ *
+ * Order means nothing among a project's members, so a writer whose object happens to hold them in
+ * another order must not move a member, which would cost the comment above it. A member the file
+ * did not have goes after the ones it did.
+ */
+function inOrderOf(config: ProjectConfig, previous: string): ProjectConfig {
+  let before: string[];
+  try {
+    before = Object.keys(parseProject(previous));
+  } catch {
+    return config;
+  }
+  if (!isJsonObject(config)) {
+    return config;
+  }
+  const source = config;
+  const keys = Object.keys(source);
+  const order = [
+    ...before.filter((key) => keys.includes(key)),
+    ...keys.filter((key) => !before.includes(key)),
+  ];
+  // SAFETY: the same members, only in another order.
+  return Object.fromEntries(order.map((key) => [key, source[key]])) as ProjectConfig;
+}

package/src/jxn/serialize.ts

@@ -12,7 +12,7 @@ import { parseJxnWithSpans } from "./parse.ts";
 import { reconcileJxn } from "./reconcile.ts";
 import type { JxnReading } from "./reconcile.ts";
 
-const INDENT = "    ";
+export const INDENT = "    ";
 
 /** Past this a line of names is worse than one name per line. */
 const WIDTH = 100;
@@ -35,7 +35,7 @@ const RESERVED_TAGS = new Set(["-", "attributes", "script", "state", "style"]);
 
 const isObject = (value: JsonValue | undefined): value is JsonObject => isJsonObject(value);
 
-const isRef = (value: JsonValue | undefined): value is { $ref: string } =>
+export const isRef = (value: JsonValue | undefined): value is { $ref: string } =>
   isObject(value) && isString(value.$ref) && Object.keys(value).length === 1;
 
 /** Whether a string has no lone surrogate. A `u` regular expression sees one as a code point. */
@@ -129,7 +129,7 @@ function writeString(value: string, indent: string, where: string): string {
 }
 
 /** A key, as a node or property name. Never multi-line: a name is one line. */
-function writeName(key: string, where: string): string {
+export function writeName(key: string, where: string): string {
   if (!isWellFormed(key)) {
     throw new JxnError(`${where} is a key with a lone surrogate, which Jx Notation cannot spell`);
   }
@@ -137,7 +137,7 @@ function writeName(key: string, where: string): string {
 }
 
 /** A value that fits in one token, or null if it needs a block. */
-function scalar(value: JsonValue | undefined, indent: string, where: string): string | null {
+export function scalar(value: JsonValue | undefined, indent: string, where: string): string | null {
   if (value === null) {
     return "#null";
   }
@@ -157,7 +157,7 @@ function scalar(value: JsonValue | undefined, indent: string, where: string): st
 }
 
 /** A pointer one step on. */
-const down = (where: string, key: string | number): string =>
+export const down = (where: string, key: string | number): string =>
   `${where}/${String(key).replaceAll("~", "~0").replaceAll("/", "~1")}`;
 
 /** Whether a function has a spelling as a `(fn)` node, rather than as a plain block. */
@@ -205,7 +205,7 @@ function writeFunction(key: string, fn: JsonObject, indent: string, where: strin
 }
 
 /** A JSON block. */
-function writeValue(key: string, value: JsonValue, indent: string, where: string): string[] {
+export function writeValue(key: string, value: JsonValue, indent: string, where: string): string[] {
   const name = writeName(key, where);
   const head = indent + name;
   const single = scalar(value, indent, where);
@@ -480,7 +480,7 @@ function pushMember(
 }
 
 /** A file's `$head`, whose rows are elements. */
-function writeHeadBlock(head: JsonValue[], indent: string): string[] {
+export function writeHeadBlock(head: JsonValue[], indent: string): string[] {
   return [
     "$head {",
     ...head.flatMap((row, index) =>

package/src/project-file-node.ts

@@ -16,10 +16,22 @@ import {
   lstatSync,
   openSync,
   readFileSync,
+  statSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { PROJECT_FILE_NAME, findEnclosingProject, parseProjectFile } from "./project-file.ts";
-import type { EnclosingProject, ProjectFileRead, ProjectWalkIo } from "./project-file.ts";
+import {
+  NEW_PROJECT_FILE_NAME,
+  ProjectFileConflictError,
+  findEnclosingProject,
+  parseProjectFile,
+  pickProjectFileName,
+} from "./project-file.ts";
+import type {
+  EnclosingProject,
+  ProjectFileName,
+  ProjectFileRead,
+  ProjectWalkIo,
+} from "./project-file.ts";
 
 /** Larger than any real project file, and small enough to read before anyone has answered. */
 const MAX_PROJECT_FILE_BYTES = 4 * 1024 * 1024;
@@ -83,24 +95,80 @@ function readCandidate(path: string): string | null {
 export const NODE_PROJECT_WALK_IO: ProjectWalkIo = { dirname, join, readText: readCandidate };
 
 /**
- * The project file's path in a folder.
+ * Which project file a folder holds.
+ *
+ * @param root The folder.
+ * @returns Its name; "conflict" when the folder holds both; null when it holds neither.
+ */
+export function projectFileNameIn(root: string): ProjectFileName | "conflict" | null {
+  return pickProjectFileName((name) => existsSync(join(root, name)));
+}
+
+/**
+ * The project file's path in a folder: whichever of the two names it holds, or a new project's name
+ * when it holds neither, which is where a project file would be written.
  *
  * @param root The folder.
+ * @throws {ProjectFileConflictError} When the folder holds both, which no host may choose between.
  */
 export function projectFilePath(root: string): string {
-  return join(root, PROJECT_FILE_NAME);
+  const name = projectFileNameIn(root);
+  if (name === "conflict") {
+    throw new ProjectFileConflictError(root);
+  }
+  return join(root, name ?? NEW_PROJECT_FILE_NAME);
+}
+
+/** Which project file a folder holds, and when it last changed: what a cache of it keys on. */
+export interface ProjectFileStamp {
+  mtime: number;
+  path: string;
+}
+
+/**
+ * The project file a folder holds and when it last changed.
+ *
+ * A cache compares both, because converting a project changes which file it is and need not change
+ * the time.
+ *
+ * @param root The folder.
+ * @returns Null when the folder holds no project file, or holds both, which is no project to serve
+ *   until the person editing it chooses.
+ */
+export function projectFileStamp(root: string): ProjectFileStamp | null {
+  const name = projectFileNameIn(root);
+  if (name === null || name === "conflict") {
+    return null;
+  }
+  const path = join(root, name);
+  const mtime = statSync(path, { throwIfNoEntry: false })?.mtimeMs;
+  return mtime === undefined ? null : { mtime, path };
 }
 
 /**
- * Whether a folder named explicitly holds a project file.
+ * Whether a cached stamp still describes the file.
+ *
+ * @param cached What the cache holds.
+ * @param stamp What the folder holds now.
+ */
+export function isSameStamp(
+  cached: ProjectFileStamp | undefined,
+  stamp: ProjectFileStamp,
+): boolean {
+  return cached !== undefined && cached.mtime === stamp.mtime && cached.path === stamp.path;
+}
+
+/**
+ * Whether a folder named explicitly holds a project file, of either name.
  *
  * By name alone, because the caller has already said this is the project. A search, which could
- * land on a page by that name, uses {@link findEnclosingProjectOnDisk}.
+ * land on a page by that name, uses {@link findEnclosingProjectOnDisk}. A folder holding both files
+ * holds one, and reading it reports the conflict.
  *
  * @param root The folder.
  */
 export function hasProjectFile(root: string): boolean {
-  return existsSync(projectFilePath(root));
+  return projectFileNameIn(root) !== null;
 }
 
 /**
@@ -120,10 +188,16 @@ export function findEnclosingProjectOnDisk(
  * Read a folder's project file.
  *
  * @param root The folder.
- * @returns What it holds or what is wrong with it, or null when it has none.
+ * @returns What it holds or what is wrong with it, a folder holding both files included, or null
+ *   when it has none.
  */
 export function readProjectFile(root: string): ProjectFileRead | null {
-  const path = projectFilePath(root);
+  let path: string;
+  try {
+    path = projectFilePath(root);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error), path: root, text: "" };
+  }
   try {
     return parseProjectFile(path, readFileSync(path, "utf8"));
   } catch {

package/src/project-file.ts

@@ -1,6 +1,6 @@
 /**
- * What makes a file named `project.json` a project's configuration, and which project encloses a
- * path.
+ * What makes a file named `project.jxn` or `project.json` a project's configuration, and which
+ * project encloses a path (`site-architecture.md` §2.3).
  *
  * A name is not enough. `pages/project.json` is a legal page with the route `/project`, and Nx
  * keeps its own `project.json` in every package of a workspace, so a walker that believes the name
@@ -18,11 +18,35 @@
  */
 import { isNonNullObject } from "./guards.ts";
 import { rewriteJson } from "./json-layout.ts";
+import { classifyJxn } from "./jxn/classify.ts";
+import { isJxnPath } from "./jxn/document.ts";
+import { parseProject, serializeProject } from "./jxn/project.ts";
 import { parseProjectConfig } from "./parse.ts";
 import type { ProjectConfig } from "../types.ts";
 
-/** The file that declares a project. */
-export const PROJECT_FILE_NAME = "project.json";
+/**
+ * The names a project file may have. Neither is preferred: a folder holding both is refused,
+ * because silently reading one would leave the other looking live and not being so.
+ */
+export const PROJECT_FILE_NAMES = ["project.jxn", "project.json"] as const;
+
+/** One of {@link PROJECT_FILE_NAMES}. */
+export type ProjectFileName = (typeof PROJECT_FILE_NAMES)[number];
+
+/**
+ * What a new project's file is called (`site-architecture.md` §2.4). Never what an existing
+ * project's is: that is whichever of {@link PROJECT_FILE_NAMES} its folder holds.
+ */
+export const NEW_PROJECT_FILE_NAME: ProjectFileName = "project.jxn";
+
+/**
+ * Whether a file name is one a project file may have.
+ *
+ * @param name A bare file name, with no folder.
+ */
+export function isProjectFileName(name: string | null | undefined): name is ProjectFileName {
+  return name === "project.jxn" || name === "project.json";
+}
 
 /**
  * Whether a project-relative path is the project's own file.
@@ -33,7 +57,50 @@ export const PROJECT_FILE_NAME = "project.json";
  * @param path A path relative to the project's root.
  */
 export function isProjectConfigPath(path: string | null | undefined): boolean {
-  return path === PROJECT_FILE_NAME;
+  return isProjectFileName(path);
+}
+
+/**
+ * The file name at the end of a path, in either separator.
+ *
+ * @param path A path.
+ */
+export function baseName(path: string): string {
+  return path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
+}
+
+/**
+ * What a folder holding both project files is told.
+ *
+ * @param root The folder, as the person will recognise it.
+ */
+export function projectFileConflict(root: string): string {
+  return `${root} holds both project.jxn and project.json, and a project has one. Keep the one you edit and delete the other`;
+}
+
+/** A folder holding both project files. */
+export class ProjectFileConflictError extends Error {
+  /** @param root The folder. */
+  constructor(root: string) {
+    super(projectFileConflict(root));
+    this.name = "ProjectFileConflictError";
+  }
+}
+
+/**
+ * Which project file a folder holds, from the names in it.
+ *
+ * @param has Whether the folder holds a file by this name.
+ * @returns The name; "conflict" when it holds both; null when neither.
+ */
+export function pickProjectFileName(
+  has: (name: ProjectFileName) => boolean,
+): ProjectFileName | "conflict" | null {
+  const found = PROJECT_FILE_NAMES.filter((name) => has(name));
+  if (found.length > 1) {
+    return "conflict";
+  }
+  return found[0] ?? null;
 }
 
 /**
@@ -55,21 +122,30 @@ const DOCUMENT_KEYS = [
 const NX_KEYS = ["projectType", "sourceRoot", "targets"] as const;
 
 /**
- * What a file named `project.json` turned out to be.
+ * What a file named `project.jxn` or `project.json` turned out to be.
  *
  * - `project`: a project's configuration.
- * - `other`: valid JSON that is something else, so the search goes on past it.
- * - `unreadable`: not JSON. Believed, and reported, because this is most likely a project with a typo
+ * - `other`: something else, such as a page by that name, so the search goes on past it.
+ * - `unreadable`: neither. Believed, and reported, because this is most likely a project with a typo
  *   in it, and the person who made the typo needs to hear about it.
  */
 export type ProjectFileVerdict = "other" | "project" | "unreadable";
 
 /**
- * Classify the text of a file named `project.json`.
+ * Classify the text of a project file candidate.
+ *
+ * A `project.jxn` says what it is with its first node (`spec.md` §22.5), which is read without
+ * parsing the file, so a typo further down still leaves its folder a project. A `project.json` is
+ * judged by its members, because JSON has no way to say.
  *
  * @param text The file's text.
+ * @param path The file's name or path, which decides the format.
  */
-export function classifyProjectFile(text: string): ProjectFileVerdict {
+export function classifyProjectFile(text: string, path = "project.json"): ProjectFileVerdict {
+  if (isJxnPath(path)) {
+    const kind = classifyJxn(text);
+    return kind === "document" ? "other" : kind;
+  }
   let parsed: unknown;
   try {
     parsed = JSON.parse(text);
@@ -97,11 +173,12 @@ export interface ProjectWalkIo {
 
 /** The project a walk found. */
 export interface EnclosingProject {
-  /** The project file's path. */
+  /** The project file's path; with a conflict, the `project.jxn` of the two. */
   projectFile: string;
   /** The folder holding it. */
   root: string;
-  verdict: Exclude<ProjectFileVerdict, "other">;
+  /** What it is: a project, a project that cannot be read, or a folder holding both files. */
+  verdict: Exclude<ProjectFileVerdict, "other"> | "conflict";
 }
 
 /**
@@ -117,11 +194,15 @@ export function findEnclosingProject(
   io: ProjectWalkIo,
   stopAt?: string,
 ): EnclosingProject | null {
-  const projectFile = io.join(startDirectory, PROJECT_FILE_NAME);
-  const text = io.readText(projectFile);
-  const verdict = text === null ? "other" : classifyProjectFile(text);
-  if (verdict !== "other") {
-    return { projectFile, root: startDirectory, verdict };
+  const found = PROJECT_FILE_NAMES.flatMap((name) => {
+    const projectFile = io.join(startDirectory, name);
+    const text = io.readText(projectFile);
+    const verdict = text === null ? "other" : classifyProjectFile(text, name);
+    return verdict === "other" ? [] : [{ projectFile, root: startDirectory, verdict }];
+  });
+  const [first] = found;
+  if (first) {
+    return found.length > 1 ? { ...first, verdict: "conflict" } : first;
   }
   const parent = io.dirname(startDirectory);
   return startDirectory === stopAt || parent === startDirectory
@@ -146,18 +227,40 @@ export type ProjectFileRead =
  */
 export function parseProjectFile(path: string, text: string): ProjectFileRead {
   try {
-    return { config: parseProjectConfig(text, path), path, text };
+    return { config: parseProjectSource(text, path), path, text };
   } catch (error) {
     return { error: error instanceof Error ? error.message : String(error), path, text };
   }
 }
 
+/**
+ * Parse a project file's text in the format its name says.
+ *
+ * @param text The file's text.
+ * @param path The file's path, which decides the format and names it in an error.
+ * @throws {Error} When it does not read: a `JxnError`, with a line and column, for `project.jxn`.
+ */
+export function parseProjectSource(text: string, path: string): ProjectConfig {
+  return isJxnPath(path) ? parseProject(text, path) : parseProjectConfig(text, path);
+}
+
 /**
  * Write a project's configuration, keeping as much of the text it replaces as can be kept.
  *
+ * A `project.jxn` keeps its comments through the merge `spec.md` §22.4 describes, and a
+ * `project.json` keeps its layout.
+ *
  * @param config The configuration.
  * @param previous The file's current text, or null for a new one.
+ * @param path The file's path, which decides the format. A new project's name without one.
+ * @throws {Error} When a `project.jxn` holds what Jx Notation cannot spell, naming the pointer.
  */
-export function serializeProjectFile(config: ProjectConfig, previous: string | null): string {
-  return rewriteJson(config, previous);
+export function serializeProjectFile(
+  config: ProjectConfig,
+  previous: string | null,
+  path: string = NEW_PROJECT_FILE_NAME,
+): string {
+  return isJxnPath(path)
+    ? serializeProject(config, previous ?? undefined)
+    : rewriteJson(config, previous);
 }

package/src/validate-project.ts

@@ -1,12 +1,12 @@
 /**
- * Validate-project — project.json validation against the generated per-project entry schema
+ * Validate-project — project file validation against the generated per-project entry schema
  * (specs/extensions.md §5.4).
  *
  * Node-only by design (mirrors the dynamic-ajv-import pattern of `validateDocument`): reads
- * `<root>/project.json` and `<root>/project.schema.json`, compiles the entry document with
- * ajv-2020, and resolves its relative `$ref`s through a file loader restricted to the project root
- * and its node_modules. The entry file's URL is injected as `$id` at load time so the committed,
- * machine-path-free relative refs resolve.
+ * `<root>/project.jxn` or `<root>/project.json`, and `<root>/project.schema.json`, compiles the
+ * entry document with ajv-2020, and resolves its relative `$ref`s through a file loader restricted
+ * to the project root and its node_modules. The entry file's URL is injected as `$id` at load time
+ * so the committed, machine-path-free relative refs resolve.
  *
  * When a `./node_modules/...` ref does not exist on disk (workspace hoisting leaves in-repo
  * starters without their own node_modules), the loader falls back to host resolution of the bare
@@ -15,15 +15,21 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { isAbsolute, relative, resolve } from "node:path";
+import { basename, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import type { JsonObject, JsonValue } from "../types";
+import { isJsonObject, isNonNullObject, isString } from "./guards.ts";
+import { isJxnPath } from "./jxn/document.ts";
+import { scalar } from "./jxn/serialize.ts";
+import { parseProjectSource } from "./project-file.ts";
 import { projectFilePath } from "./project-file-node.ts";
 
 export interface ProjectValidationResult {
   valid: boolean;
   errors: unknown[] | null;
+  /** The project file's name, `project.jxn` or `project.json`, which a report names. */
+  file: string;
 }
 
 // Minimal structural types for the optional `ajv` peer dependency (no direct dependency, and it
@@ -67,16 +73,18 @@ export async function validateProjectFile(projectRoot: string): Promise<ProjectV
   const schemaPath = resolve(root, "project.schema.json");
 
   if (!existsSync(projectPath)) {
-    throw new Error(`project.json not found in ${root}`);
+    throw new Error(`No project.jxn or project.json in ${root}`);
   }
   if (!existsSync(schemaPath)) {
     throw new Error(
       `project.schema.json not found in ${root} — run \`jx schema\` to generate it from ` +
-        `project.json#/extensions`,
+        `the project file's extensions`,
     );
   }
 
-  const project = readJson(projectPath);
+  /* SAFETY: both readers answer an object: `parseProjectConfig` refuses anything else, and the
+     project grammar has no top level but the configuration's members. */
+  const project = parseProjectSource(readFileSync(projectPath, "utf8"), projectPath) as JsonObject;
   /*
    * SAFETY: project.schema.json is written by `jx schema` (emitProjectSchema), which always emits a
    * JSON object. A hand-damaged file that is not one fails loudly either way: the `$id` write below
@@ -108,7 +116,60 @@ export async function validateProjectFile(projectRoot: string): Promise<ProjectV
 
   const validate = await ajv.compileAsync(entrySchema);
   const valid = validate(project);
-  return { errors: validate.errors ?? null, valid };
+  const errors = validate.errors ?? null;
+  return {
+    errors: errors && isJxnPath(projectPath) ? explainJxnLists(errors, project) : errors,
+    file: basename(projectPath),
+    valid,
+  };
+}
+
+/** The value at a JSON Pointer. */
+function valueAt(document: JsonValue, pointer: string): JsonValue | undefined {
+  let current: JsonValue | undefined = document;
+  for (const part of pointer.split("/").slice(1)) {
+    const key = part.replaceAll("~1", "/").replaceAll("~0", "~");
+    current = Array.isArray(current)
+      ? current[Number(key)]
+      : isJsonObject(current)
+        ? current[key]
+        : undefined;
+  }
+  return current;
+}
+
+/**
+ * Say how to write a list of one in Jx Notation, where it is the mistake people make by hand.
+ *
+ * `extensions "@jxsuite/parser"` reads as a string, so the schema's "must be array" is true and of
+ * no help. Coercing from the schema instead would make the reader need the schema.
+ *
+ * @param errors Ajv's errors.
+ * @param project What the file read to.
+ */
+export function explainJxnLists(errors: unknown[], project: JsonValue): unknown[] {
+  return errors.map((error) => {
+    if (
+      !isNonNullObject(error) ||
+      !("keyword" in error) ||
+      error.keyword !== "type" ||
+      !("params" in error) ||
+      !isNonNullObject(error.params) ||
+      !("type" in error.params) ||
+      error.params.type !== "array" ||
+      !("instancePath" in error) ||
+      !isString(error.instancePath)
+    ) {
+      return error;
+    }
+    const value = valueAt(project, error.instancePath);
+    const spelled = scalar(value, "", error.instancePath);
+    const key = error.instancePath.split("/").at(-1) ?? "";
+    if (spelled === null || spelled.includes("\n") || key === "") {
+      return error;
+    }
+    return { ...error, message: `must be a list, written as ${key} { - ${spelled} }` };
+  });
 }
 
 /**