@specforge/cli 0.1.0 → 0.2.4

package/node_modules/@specforge/spec-types/dist/schema/entity-field-schemas.js

@@ -0,0 +1,181 @@
+/**
+ * MB.1.1 — the canonical entity → field → Zod-schema map for the spec/epic/ticket
+ * `a.json()` fields, plus the write-boundary id/order filler (`ensureItemIds`) that
+ * is the symmetric counterpart of the read-boundary parser.
+ *
+ * This lives in `@specforge/spec-types` (not `@specforge/operations`) because it is
+ * the SINGLE shared source for BOTH boundaries:
+ *   - the read parser (`@specforge/operations` `parseEntityJsonFields`) safeParses each
+ *     field against `ENTITY_FIELD_SCHEMAS[entity][field]`, and
+ *   - the write filler (`ensureItemIds`, below) mints the schema-required internal id
+ *     (+ positional order) into the same fields BEFORE the write,
+ * so a field can never be written in a shape the read parser then drops. It also has
+ * to be importable by `@specforge/lifecycle` (the planning write path), which is
+ * forbidden from importing `@specforge/operations` (pure-orchestration lint rule) —
+ * spec-types is the one home both packages may depend on.
+ *
+ * ## The bug `ensureItemIds` closes
+ *
+ * The planning actor writes the spec/epic array-of-object fields (`goals`,
+ * `acceptanceCriteria`, `apiContracts`, `requirements`, …) WITHOUT the internal `id`
+ * (and, for `acceptanceCriteria`, `order`). The write accepts them silently, but on
+ * the CPS re-read the parser safeParses each against the canonical Zod schema — which
+ * REQUIRES `id` (and `order`) — fails, and DROPS the whole array. The gate then never
+ * sees the filled fields, so the phase is unclosable (MB.1 root cause, run
+ * 20260708184523-801371).
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { GoalSchema, RequirementSchema, NonFunctionalRequirementSchema, GuardrailSchema, TechStackItemSchema, StructureItemSchema, ScopeSchema, SharedPatternSchema, ApiContractSchema, EpicTargetsSchema, } from './planning/index.js';
+import { AcceptanceCriterionSchema, FieldDeclarationSchema, CodeReferenceSchema, TypeReferenceSchema, } from './auxiliary.js';
+/** `fieldDeclarations` is a map of key → { value:'N/A', reason } on all three entities. */
+const FieldDeclarationsSchema = z.record(z.string(), FieldDeclarationSchema);
+/**
+ * Per-field lenient schemas, keyed by entity. A field present in the read parser's
+ * canonical `a.json()` list but ABSENT here (`dependencyTree`, `statusHistory`) has
+ * no canonical schema — it is `JSON.parse`d but not schema-validated on read, and it
+ * carries no `id`, so `ensureItemIds` leaves it untouched.
+ */
+export const ENTITY_FIELD_SCHEMAS = {
+    spec: {
+        goals: z.array(GoalSchema),
+        requirements: z.array(RequirementSchema),
+        nonFunctionalRequirements: z.array(NonFunctionalRequirementSchema),
+        acceptanceCriteria: z.array(AcceptanceCriterionSchema),
+        guardrails: z.array(GuardrailSchema),
+        techStack: z.array(TechStackItemSchema),
+        folderStructures: z.array(StructureItemSchema),
+        scope: ScopeSchema,
+        sharedPatterns: z.array(SharedPatternSchema),
+        epicTargets: EpicTargetsSchema,
+        fieldDeclarations: FieldDeclarationsSchema,
+        // dependencyTree — no canonical spec-types schema; JSON.parse only.
+    },
+    epic: {
+        scope: ScopeSchema,
+        goals: z.array(GoalSchema),
+        acceptanceCriteria: z.array(AcceptanceCriterionSchema),
+        apiContracts: z.array(ApiContractSchema),
+        sharedPatterns: z.array(SharedPatternSchema),
+        fileStructures: z.array(StructureItemSchema),
+        fieldDeclarations: FieldDeclarationsSchema,
+    },
+    ticket: {
+        codeReferences: z.array(CodeReferenceSchema),
+        typeReferences: z.array(TypeReferenceSchema),
+        fieldDeclarations: FieldDeclarationsSchema,
+        // statusHistory — no canonical spec-types schema; JSON.parse only.
+    },
+};
+// ---------------------------------------------------------------------------
+// ensureItemIds — write-boundary id/order filler (schema-driven, recursive)
+// ---------------------------------------------------------------------------
+/**
+ * Peel the transparent wrappers (`.optional()`, `.nullable()`, `.default()`,
+ * `.refine()`/`.transform()`) so we can inspect the underlying array/object schema.
+ * Bounded loop so a pathological schema can never spin.
+ */
+function unwrap(schema) {
+    let s = schema;
+    for (let i = 0; i < 16; i++) {
+        if (s instanceof z.ZodOptional || s instanceof z.ZodNullable) {
+            s = s.unwrap();
+        }
+        else if (s instanceof z.ZodDefault) {
+            s = s.removeDefault();
+        }
+        else if (s instanceof z.ZodEffects) {
+            s = s.innerType();
+        }
+        else {
+            break;
+        }
+    }
+    return s;
+}
+/**
+ * If `schema` (once unwrapped) is `z.array(<ZodObject>)`, return the element object
+ * schema; otherwise `null`. The element is itself unwrapped so a wrapped element
+ * (rare) is still resolved.
+ */
+function arrayOfObjectElement(schema) {
+    const base = unwrap(schema);
+    if (!(base instanceof z.ZodArray))
+        return null;
+    const element = unwrap(base.element);
+    return element instanceof z.ZodObject ? element : null;
+}
+/** True when the object schema declares an `id` field. */
+function hasIdField(elem) {
+    return 'id' in elem.shape;
+}
+/**
+ * Fill id/order into every item of `value` against `elemSchema`, then recurse into
+ * any nested array-of-object-with-id field. Leaves non-array values and non-object
+ * items untouched. Returns a NEW array of shallow-copied items (never mutates input).
+ */
+function fillObjectArray(value, elemSchema, idGen) {
+    if (!Array.isArray(value))
+        return value;
+    const shape = elemSchema.shape;
+    const hasId = 'id' in shape;
+    const hasOrder = 'order' in shape;
+    // Precompute the nested array-of-object-with-id fields once (per element schema).
+    const nested = [];
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        const el = arrayOfObjectElement(fieldSchema);
+        if (el && hasIdField(el))
+            nested.push({ field: key, elem: el });
+    }
+    return value.map((raw, i) => {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+            return raw;
+        const item = { ...raw };
+        // id: ALWAYS auto (regenerated even if present) — internal identity, not a FK.
+        if (hasId)
+            item['id'] = idGen();
+        // order: respect the agent's value; auto-fill by 1-based position only if absent.
+        if (hasOrder && typeof item['order'] !== 'number')
+            item['order'] = i + 1;
+        for (const { field, elem } of nested) {
+            if (field in item)
+                item[field] = fillObjectArray(item[field], elem, idGen);
+        }
+        return item;
+    });
+}
+/**
+ * Return a shallow copy of `fields` with the `a.json()` array-of-object fields of
+ * `entity` carrying a minted `id` (always) + positional `order` (only where the item
+ * schema has one, and only when the agent omitted it), RECURSIVELY (covers e.g.
+ * `spec.requirements[].acceptanceCriteria[]`).
+ *
+ * Policy (MB.1 decisions, locked 2026-07-08):
+ *  - `id` is INTERNAL identity, ALWAYS auto-minted (regenerated even if one is
+ *    present). The agent never sends it; the validator ignores it (these embedded ids
+ *    are NOT foreign keys — unlike ticket AC, which are separate entities). The agent
+ *    re-sends the whole array each update, so ids churn per write — that churn is inert
+ *    and accepted.
+ *  - `order` RESPECTS an agent-provided value; it is auto-filled by 1-based position
+ *    ONLY when absent.
+ *
+ * Never validates content, never throws. Non-array / unknown fields (and the whole
+ * `ticket` entity, whose sub-arrays are normalized into child tables that already
+ * stamp id+order — MB.1 §0.1) pass through verbatim.
+ *
+ * @param idGen deterministic id source for tests; defaults to `randomUUID`.
+ */
+export function ensureItemIds(fields, entity, idGen = () => randomUUID()) {
+    const schemas = ENTITY_FIELD_SCHEMAS[entity];
+    const out = { ...fields };
+    for (const [field, schema] of Object.entries(schemas)) {
+        if (!(field in out) || out[field] === undefined || out[field] === null)
+            continue;
+        const elem = arrayOfObjectElement(schema);
+        if (elem && hasIdField(elem)) {
+            out[field] = fillObjectArray(out[field], elem, idGen);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=entity-field-schemas.js.map

package/node_modules/@specforge/spec-types/dist/schema/entity-field-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-field-schemas.js","sourceRoot":"","sources":["../../src/schema/entity-field-schemas.ts"],"names":[],"mappings":"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"}