@promptctl/cc-candybar 1.0.0

package/src/config/loader/merge.ts

@@ -0,0 +1,40 @@
+// [LAW:one-source-of-truth] The single point that consults DEFAULT_DSL_CONFIG to
+// fill missing keys. A user file declares only what differs; the cascade here
+// (shallow-merge globals, by-name merge variables/segments/actions, wholesale
+// root replacement) is the one place "absent means inherit" is decided.
+// This file changes when the merge semantics change.
+
+import { type DslConfig, type RawDslConfig } from "../dsl-types.js";
+import { DEFAULT_DSL_CONFIG } from "../default-dsl-config.js";
+
+/**
+ * Merge a RawDslConfig on top of a default DslConfig. Pure function.
+ *
+ *   globals    : shallow merge per field (user wins per-field)
+ *   variables  : merge by name (user wins per-name)
+ *   segments   : merge by name (user wins per-name)
+ *   root       : the canonical layout tree. Authored via the A-grammar (`root`)
+ *                replaces wholesale; absent → default's tree.
+ *                [LAW:one-source-of-truth] `layout:` is rejected at parse time
+ *                with a migration error (removed in 2de.19), so only `root`
+ *                ever reaches this function.
+ */
+export function mergeWithDefault(
+  raw: RawDslConfig,
+  dflt: DslConfig = DEFAULT_DSL_CONFIG,
+): DslConfig {
+  return {
+    globals: { ...dflt.globals, ...(raw.globals ?? {}) },
+    variables: { ...dflt.variables, ...(raw.variables ?? {}) },
+    segments: { ...dflt.segments, ...(raw.segments ?? {}) },
+    root: raw.root !== undefined ? raw.root : dflt.root,
+    // [LAW:one-source-of-truth] actions merge by name, same cascade — a user
+    // declares only the actions that differ from the bundled default (which
+    // ships none).
+    actions: { ...dflt.actions, ...(raw.actions ?? {}) },
+    // [LAW:one-source-of-truth] helpers merge by name, same cascade — a user
+    // overrides one formatter helper by re-declaring its name; the rest inherit
+    // from the bundled default.
+    helpers: { ...dflt.helpers, ...(raw.helpers ?? {}) },
+  };
+}

package/src/config/loader/refs.ts

@@ -0,0 +1,96 @@
+// [LAW:dataflow-not-control-flow] Best-effort extraction of the references a
+// template string makes — dotted variable refs, `action "name"` refs, and
+// `picker "apply" "page"` refs. Pure text walks over `{{ … }}` blocks: no
+// full template parse (that is the engine's compile-time job). This file changes
+// when the surface grammar of those refs changes; the cross-ref/cycle passes
+// consume the sets it returns without re-deriving them.
+
+const TEMPLATE_BLOCK_RE = /{{([\s\S]*?)}}/g;
+const STRING_LITERAL_RE = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`[^`]*`/g;
+const DOTTED_REF_RE =
+  /(?<![A-Za-z0-9_)])\.([A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)*)/g;
+
+// [LAW:dataflow-not-control-flow] Extract every `.<id>(.<id>)*` token inside
+// `{{ ... }}` blocks after stripping string literals. The result is a set of
+// dotted reference candidates; the caller decides which are valid.
+export function extractTemplateRefs(template: string): Set<string> {
+  const refs = new Set<string>();
+  let m: RegExpExecArray | null;
+  TEMPLATE_BLOCK_RE.lastIndex = 0;
+  while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
+    const block = m[1]!.replace(STRING_LITERAL_RE, "");
+    let r: RegExpExecArray | null;
+    DOTTED_REF_RE.lastIndex = 0;
+    while ((r = DOTTED_REF_RE.exec(block)) !== null) {
+      refs.add(r[1]!);
+    }
+  }
+  return refs;
+}
+
+// [LAW:dataflow-not-control-flow] Extract every `action "name"` call from a
+// template, for the load-time existence check. Same best-effort code-span /
+// string-literal walk as extractTemplateRefs: the `action` keyword lives in a
+// CODE span and its NAME is the very next string literal (the display/boundValue
+// literals that follow are preceded by a non-`action` span, so they are never
+// misread as the name).
+const ACTION_ARG_RE = /\baction\s+$/;
+export function extractActionRefs(template: string): Set<string> {
+  const refs = new Set<string>();
+  TEMPLATE_BLOCK_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
+    const block = m[1]!;
+    let cursor = 0;
+    let s: RegExpExecArray | null;
+    STRING_LITERAL_RE.lastIndex = 0;
+    while ((s = STRING_LITERAL_RE.exec(block)) !== null) {
+      if (ACTION_ARG_RE.test(block.slice(cursor, s.index))) {
+        refs.add(s[0].slice(1, -1));
+      }
+      cursor = s.index + s[0].length;
+    }
+  }
+  return refs;
+}
+
+// [LAW:dataflow-not-control-flow] Extract the action names a `picker` call
+// references — its FIRST TWO string-literal args are the apply action and the
+// page action (`{{ picker "applyTheme" "themePage" true true }}`). Same code/
+// string-span walk as extractActionRefs; the picker keyword arms the next literal
+// as the apply name and the one after it as the page name (the trailing bool args
+// are not string literals, so they are never captured).
+const PICKER_ARG_RE = /\bpicker\s+$/;
+export function extractPickerRefs(template: string): Set<string> {
+  const refs = new Set<string>();
+  TEMPLATE_BLOCK_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
+    const block = m[1]!;
+    let cursor = 0;
+    let pending = 0; // remaining name args to capture for the current picker call
+    let s: RegExpExecArray | null;
+    STRING_LITERAL_RE.lastIndex = 0;
+    while ((s = STRING_LITERAL_RE.exec(block)) !== null) {
+      if (PICKER_ARG_RE.test(block.slice(cursor, s.index))) pending = 2;
+      if (pending > 0) {
+        refs.add(s[0].slice(1, -1));
+        pending--;
+      }
+      cursor = s.index + s[0].length;
+    }
+  }
+  return refs;
+}
+
+// A ref resolves if (a) the full dotted name is a declared variable, OR
+// (b) it's a strict prefix of some declared variable (namespace navigation
+// like .session in `.session.id` when only `session.id` is declared).
+export function refResolves(ref: string, allVars: Set<string>): boolean {
+  if (allVars.has(ref)) return true;
+  const prefix = `${ref}.`;
+  for (const name of allVars) {
+    if (name.startsWith(prefix)) return true;
+  }
+  return false;
+}

package/src/config/loader/segments.ts

@@ -0,0 +1,120 @@
+// [LAW:types-are-the-program] The segment schema: a required `template` plus
+// optional layout/paint/visibility fields and a nested `vars` block (validated by
+// the variable schema). Declared as DATA (SEGMENT_SCHEMA) and interpreted by the
+// generic `record` engine — a plain record with no cross-field invariant, so two
+// value-shaped fields (`width`, `vars`) carry their bespoke parse as field specs.
+// This file changes when a segment field is added or removed.
+
+import {
+  JUSTIFY_MODES,
+  TRUNCATE_MODES,
+  type SegmentDecl,
+  type VariableDecl,
+} from "../dsl-types.js";
+import { findKeyLine } from "./diagnostics.js";
+import {
+  describeType,
+  describeValue,
+  isPlainObject,
+  optionalEnumSpec,
+  optionalStringSpec,
+  paletteSpec,
+  record,
+  recordJson,
+  requireStringSpec,
+  type FieldSpec,
+  type FieldSpecMap,
+  type JsonNode,
+  type RecordSchema,
+  type ValidateCtx,
+} from "./validate-core.js";
+import { validateVariables, variablesMapJson } from "./variables.js";
+
+export function validateSegments(
+  ctx: ValidateCtx,
+  raw: unknown,
+): Record<string, SegmentDecl> {
+  if (raw === undefined) return {};
+  if (!isPlainObject(raw)) {
+    ctx.issues.push({
+      path: "segments",
+      message: `segments must be an object, got ${describeType(raw)}`,
+      line: findKeyLine(ctx.source, ["segments"]),
+    });
+    return {};
+  }
+
+  const out: Record<string, SegmentDecl> = {};
+  for (const [name, decl] of Object.entries(raw)) {
+    const parsed = record(ctx, SEGMENT_SCHEMA, `segments.${name}`, decl);
+    if (parsed !== null) out[name] = parsed;
+  }
+  return out;
+}
+
+// [LAW:types-are-the-program] `width` is `"auto"` or a positive integer — a union
+// the generic string/enum specs cannot express, so it carries its own parse and
+// bespoke message as DATA. Absent → omitted; present-and-wrong → issue + omitted.
+function widthSpec(): FieldSpec<"auto" | number> {
+  return {
+    required: false,
+    json: { anyOf: [{ const: "auto" }, { type: "integer", minimum: 1 }] },
+    parse: (ctx, path, field, raw) => {
+      const v = raw[field];
+      if (v === undefined) return undefined;
+      if (v === "auto") return "auto";
+      if (typeof v === "number" && Number.isInteger(v) && v > 0) return v;
+      ctx.issues.push({
+        path: `${path}.${field}`,
+        message: `width must be "auto" or a positive integer, got ${describeValue(v)}`,
+        line: findKeyLine(ctx.source, [...path.split("."), field]),
+      });
+      return undefined;
+    },
+  };
+}
+
+// [LAW:decomposition] The nested `vars` block defers to the variable schema —
+// recursion by reuse of the already-migrated per-name taggedUnion, not a new
+// combinator. Absent → omitted; present → the parsed map (possibly empty, with
+// its own issues already reported), mirroring the old `if (raw.vars !== undefined)`.
+function varsSpec(): FieldSpec<Readonly<Record<string, VariableDecl>>> {
+  return {
+    required: false,
+    // [LAW:one-source-of-truth] The nested `vars` schema is the SAME name →
+    // VariableDecl map the top-level `variables` block emits — one source.
+    json: variablesMapJson(),
+    parse: (ctx, path, field, raw) => {
+      const v = raw[field];
+      if (v === undefined) return undefined;
+      return validateVariables(ctx, `${path}.${field}`, v);
+    },
+  };
+}
+
+// [LAW:dataflow-not-control-flow] The segment's shape as DATA over its fields, in
+// declaration order. The engine runs every spec, rejects unknown keys, and fails
+// the segment when `template` is absent or invalid — the isPlainObject guard,
+// unknown-key loop, result-threading, and optional-omission the old body hand-rolled.
+const SEGMENT_FIELDS: FieldSpecMap<SegmentDecl> = {
+  template: requireStringSpec(),
+  width: widthSpec(),
+  justify: optionalEnumSpec(JUSTIFY_MODES),
+  truncate: optionalEnumSpec(TRUNCATE_MODES),
+  bg: optionalStringSpec(),
+  fg: optionalStringSpec(),
+  when: optionalStringSpec(),
+  palette: paletteSpec(),
+  vars: varsSpec(),
+};
+
+const SEGMENT_SCHEMA: RecordSchema<SegmentDecl> = {
+  noun: "segment key",
+  fields: SEGMENT_FIELDS,
+};
+
+// [LAW:one-source-of-truth] The `segments` block is a name → SegmentDecl map,
+// derived from the SAME SEGMENT_SCHEMA the validator interprets.
+export function segmentsJson(): JsonNode {
+  return { type: "object", additionalProperties: recordJson(SEGMENT_SCHEMA) };
+}