feat(declare)!: parse role=declare blocks as YAML
Replace the tag/threshold/key/expr CSV body with YAML `vars:` and `tags:` maps. `parseDeclare` validates the body with an exported Zod schema and returns the same declaration and modifier shapes the reactivity engine already consumes. The breaking rename from `parseDeclareCsv` updates the registry, the journal re-exports, and the `tttk check` role checks, where R003 now reports schema errors with their path and R004 warns when a block declares nothing.
This commit is contained in:
hyper
@@ -1,21 +1,28 @@
|
||||
/**
|
||||
* Declare parser — parses ```csv role=declare code blocks from markdown.
|
||||
* Declare parser — parses ```yaml role=declare code blocks from markdown.
|
||||
*
|
||||
* Shared between CLI completions scanner and browser-side completions.
|
||||
* Shared between the CLI scanner/validator and the browser-side journal.
|
||||
*
|
||||
* Format (columns can be in any order; `tag` and `threshold` are optional):
|
||||
* tag,threshold,key,expr
|
||||
* ,,$hp,$con*5+$mod_hp ← variable declaration
|
||||
* ,,$ac,10+$dex ← variable declaration
|
||||
* #warrior,2,$mod_hp,20 ← tag modifier (threshold 2)
|
||||
* #warrior,,$mod_str,1 ← tag modifier (threshold defaults to 1)
|
||||
* The body is YAML with two optional maps (`declareSchema` below):
|
||||
*
|
||||
* When `tag` is empty: $key is a reactively computed variable.
|
||||
* When `tag` is present: when #tag met (source's tagmap value >= threshold),
|
||||
* $key gets expr added to its base.
|
||||
* vars:
|
||||
* $hp: $con*5 + $mod_hp
|
||||
* $ac: 10 + $dex
|
||||
* tags:
|
||||
* warrior:
|
||||
* 1:
|
||||
* $mod_hp: 20
|
||||
* 2:
|
||||
* $mod_str: 1
|
||||
*
|
||||
* `vars` entries are reactively computed variables. `tags` entries are
|
||||
* modifiers: when a source variable's tag map holds `#warrior` at a count
|
||||
* >= the threshold key, each `$target` gains the modifier value. Tag names
|
||||
* may be written with or without the leading `#`.
|
||||
*/
|
||||
|
||||
import { parse } from "csv-parse/browser/esm/sync";
|
||||
import yaml from "js-yaml";
|
||||
import { z } from "zod";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
@@ -38,65 +45,134 @@ export interface DeclareResult {
|
||||
tagModifiers: TagModifier[];
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Schema
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** A `$name` variable key. */
|
||||
const VAR_NAME = /^\$[A-Za-z_][A-Za-z0-9_]*$/;
|
||||
/** A tag name, optionally carrying its leading `#`. */
|
||||
const TAG_NAME = /^#?[A-Za-z_][A-Za-z0-9_-]*$/;
|
||||
/** Threshold map keys are positive integers (1, 2, 3, …). */
|
||||
const THRESHOLD = /^[1-9][0-9]*$/;
|
||||
|
||||
/**
|
||||
* Parse a single ```csv role=declare block body.
|
||||
* Expression text. YAML resolves bare numbers to `number`, so both strings and
|
||||
* numbers are accepted and normalized to a trimmed string. A missing value
|
||||
* loads as `null` and becomes empty text, which the refine rejects. Anything
|
||||
* else (boolean, date) is a mistake in the source. Unknown references inside
|
||||
* the expression are resolved by the reactivity engine, not here.
|
||||
*/
|
||||
export function parseDeclareCsv(csv: string, source: string): DeclareResult {
|
||||
const trimmed = csv.trim();
|
||||
const exprSchema = z
|
||||
.union([z.string(), z.number(), z.null()])
|
||||
.transform((value) => (value === null ? "" : String(value).trim()))
|
||||
.refine((value) => value.length > 0, "expression must not be empty");
|
||||
|
||||
/** A map whose keys must look like `$name`. */
|
||||
function varMap(message: string) {
|
||||
return z.record(z.string(), exprSchema).superRefine((obj, ctx) => {
|
||||
for (const key of Object.keys(obj)) {
|
||||
if (!VAR_NAME.test(key)) {
|
||||
ctx.addIssue({ code: "custom", message, path: [key] });
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/** `threshold -> { $target: expression }`. */
|
||||
const thresholdMap = z
|
||||
.record(
|
||||
z.string(),
|
||||
varMap("tag modifier targets must start with $, e.g. `$mod_hp`"),
|
||||
)
|
||||
.superRefine((obj, ctx) => {
|
||||
for (const key of Object.keys(obj)) {
|
||||
if (!THRESHOLD.test(key)) {
|
||||
ctx.addIssue({
|
||||
code: "custom",
|
||||
message: "threshold must be a positive integer",
|
||||
path: [key],
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
/** The accepted `role=declare` shape. Exported for tests and reuse. */
|
||||
export const declareSchema = z.strictObject({
|
||||
vars: varMap("variable names must start with $, e.g. `$hp`").optional(),
|
||||
tags: z
|
||||
.record(z.string(), thresholdMap)
|
||||
.superRefine((obj, ctx) => {
|
||||
for (const key of Object.keys(obj)) {
|
||||
if (!TAG_NAME.test(key)) {
|
||||
ctx.addIssue({
|
||||
code: "custom",
|
||||
message: "tag names may not contain spaces or punctuation",
|
||||
path: [key],
|
||||
});
|
||||
}
|
||||
}
|
||||
})
|
||||
.optional(),
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parsing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Parse a single ```yaml role=declare block body.
|
||||
*
|
||||
* Throws with a `path: message` summary when the body is not valid YAML or
|
||||
* does not match the schema. Callers attach the file/line context.
|
||||
*/
|
||||
export function parseDeclare(body: string): DeclareResult {
|
||||
const trimmed = body.trim();
|
||||
if (!trimmed) return { variables: [], tagModifiers: [] };
|
||||
|
||||
// Validate that required columns exist (order-agnostic, tag is optional)
|
||||
const firstLine = trimmed.split(/\r?\n/)[0];
|
||||
const headers = firstLine.split(",").map((h) => h.trim().toLowerCase());
|
||||
if (!headers.includes("key") || !headers.includes("expr")) {
|
||||
let data: unknown;
|
||||
try {
|
||||
data = yaml.load(trimmed);
|
||||
} catch (error) {
|
||||
throw new Error(
|
||||
`${source}: role=declare blocks must have "key" and "expr" columns. Got: ${headers.join(",")}`,
|
||||
`role=declare body is not valid YAML: ${errorText(error)}`,
|
||||
);
|
||||
}
|
||||
|
||||
const records = parse(trimmed, {
|
||||
columns: true,
|
||||
trim: true,
|
||||
skipEmptyLines: true,
|
||||
}) as Array<{ tag?: string; threshold?: string; key: string; expr: string }>;
|
||||
const parsed = declareSchema.safeParse(data ?? {});
|
||||
if (!parsed.success) {
|
||||
throw new Error(`role=declare: ${formatIssues(parsed.error)}`);
|
||||
}
|
||||
|
||||
const variables: VarDeclaration[] = [];
|
||||
for (const [key, expression] of Object.entries(parsed.data.vars ?? {})) {
|
||||
variables.push({ key, expression });
|
||||
}
|
||||
|
||||
const tagModifiers: TagModifier[] = [];
|
||||
|
||||
for (const row of records) {
|
||||
const tag = row.tag ?? "";
|
||||
const key = row.key ?? "";
|
||||
const expr = row.expr ?? "";
|
||||
|
||||
if (!key || !expr) {
|
||||
console.warn(`${source}: skipping row with empty key or expr`);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (tag) {
|
||||
// Tag modifier
|
||||
if (!tag.startsWith("#")) {
|
||||
throw new Error(`${source}: tag must start with #, got "${tag}"`);
|
||||
for (const [name, thresholds] of Object.entries(parsed.data.tags ?? {})) {
|
||||
const tag = name.startsWith("#") ? name : `#${name}`;
|
||||
for (const [rawThreshold, targets] of Object.entries(thresholds)) {
|
||||
const threshold = Number(rawThreshold);
|
||||
for (const [target, expression] of Object.entries(targets)) {
|
||||
tagModifiers.push({ tag, target, expression, threshold });
|
||||
}
|
||||
if (!key.startsWith("$")) {
|
||||
throw new Error(`${source}: key must start with $, got "${key}"`);
|
||||
}
|
||||
const thresholdRaw = row.threshold?.trim() ?? "";
|
||||
const threshold = thresholdRaw ? parseInt(thresholdRaw, 10) : 1;
|
||||
if (isNaN(threshold) || threshold < 1) {
|
||||
throw new Error(
|
||||
`${source}: threshold must be a positive integer, got "${row.threshold}"`,
|
||||
);
|
||||
}
|
||||
tagModifiers.push({ tag, target: key, expression: expr, threshold });
|
||||
} else {
|
||||
// Variable declaration
|
||||
if (!key.startsWith("$")) {
|
||||
throw new Error(`${source}: key must start with $, got "${key}"`);
|
||||
}
|
||||
variables.push({ key, expression: expr });
|
||||
}
|
||||
}
|
||||
|
||||
return { variables, tagModifiers };
|
||||
}
|
||||
|
||||
function formatIssues(error: z.ZodError): string {
|
||||
return error.issues
|
||||
.map((issue) =>
|
||||
issue.path.length
|
||||
? `${issue.path.join(".")}: ${issue.message}`
|
||||
: issue.message,
|
||||
)
|
||||
.join("; ");
|
||||
}
|
||||
|
||||
function errorText(error: unknown): string {
|
||||
return error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user