@aperant/framework 0.19.0 → 0.20.0

package/dist/cli/features/area-shape.mjs

@@ -0,0 +1,141 @@
+/**
+ * area-shape.mjs — hand-rolled structural validator for feature-registry
+ * area files, mirroring `src/schemas/feature-registry.ts` (FeatureRegistrySchema)
+ * PLUS the uniqueness refinement (feature ids unique per area; sub_feature ids
+ * unique per feature group).
+ *
+ * WHY A TWIN VALIDATOR EXISTS (ID-07): the bare-node CI check
+ * (`bin/features-reconcile-check.mjs`) runs with NO node_modules, so it cannot
+ * import zod. This module is node:-builtins only (in fact, zero imports).
+ * `feature-registry-schema-parity.test.ts` validates shared fixtures against
+ * BOTH this validator and the zod schema so they cannot drift.
+ *
+ * Semantics mirror zod defaults:
+ *   - unknown keys are ALLOWED (zod objects are non-strict);
+ *   - `components` and `sub_features` may be absent (zod `.default([])`);
+ *   - `route` stays required non-empty — non-routed areas use the literal
+ *     "(cross-cutting)" (chrome.json precedent), never null.
+ *
+ * Returns { ok, errors: [] } — never throws.
+ */
+const ID_RE = /^[a-z0-9-]+$/;
+const LAST_SCANNED_RE = /^\d{4}-\d{2}-\d{2}(T[\d:.Z+-]+)?$/;
+const TESTABLE_VALUES = new Set(['testable', 'observable', 'blocked']);
+const WIRED_VALUES = new Set([true, false, 'stubbed', 'partial']);
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+function checkOptionalString(errors, at, v) {
+    if (v !== undefined && !isNonEmptyString(v)) {
+        errors.push(`${at}: must be a non-empty string when present`);
+    }
+}
+function validateSubFeature(errors, at, sub) {
+    if (!sub || typeof sub !== 'object' || Array.isArray(sub)) {
+        errors.push(`${at}: must be an object`);
+        return;
+    }
+    if (!isNonEmptyString(sub.id) || !ID_RE.test(sub.id)) {
+        errors.push(`${at}.id: must match ${ID_RE}`);
+    }
+    if (!isNonEmptyString(sub.name))
+        errors.push(`${at}.name: required non-empty string`);
+    checkOptionalString(errors, `${at}.component`, sub.component);
+    if (!isNonEmptyString(sub.type))
+        errors.push(`${at}.type: required non-empty string`);
+    if (!WIRED_VALUES.has(sub.wired)) {
+        errors.push(`${at}.wired: must be true|false|"stubbed"|"partial"`);
+    }
+    if (sub.handler !== undefined && typeof sub.handler !== 'string') {
+        errors.push(`${at}.handler: must be a string when present`);
+    }
+    if (sub.shortcut !== undefined && typeof sub.shortcut !== 'string') {
+        errors.push(`${at}.shortcut: must be a string when present`);
+    }
+    if (sub.testable !== undefined && !TESTABLE_VALUES.has(sub.testable)) {
+        errors.push(`${at}.testable: must be "testable"|"observable"|"blocked" when present`);
+    }
+    if (sub.test_hint !== undefined && typeof sub.test_hint !== 'string') {
+        errors.push(`${at}.test_hint: must be a string when present`);
+    }
+    // default / range / options are `unknown` in the zod schema — anything goes.
+}
+function validateFeatureGroup(errors, at, group) {
+    if (!group || typeof group !== 'object' || Array.isArray(group)) {
+        errors.push(`${at}: must be an object`);
+        return;
+    }
+    if (!isNonEmptyString(group.id) || !ID_RE.test(group.id)) {
+        errors.push(`${at}.id: must match ${ID_RE}`);
+    }
+    if (!isNonEmptyString(group.name))
+        errors.push(`${at}.name: required non-empty string`);
+    checkOptionalString(errors, `${at}.component`, group.component);
+    if (group.sub_features !== undefined) {
+        if (!Array.isArray(group.sub_features)) {
+            errors.push(`${at}.sub_features: must be an array when present`);
+        }
+        else {
+            const seen = new Set();
+            for (const [i, sub] of group.sub_features.entries()) {
+                validateSubFeature(errors, `${at}.sub_features[${i}]`, sub);
+                const id = sub?.id;
+                if (isNonEmptyString(id)) {
+                    if (seen.has(id)) {
+                        errors.push(`${at}.sub_features[${i}].id: duplicate sub_feature id "${id}" in group`);
+                    }
+                    seen.add(id);
+                }
+            }
+        }
+    }
+}
+/**
+ * Structural + uniqueness validation of an area-file value.
+ *
+ * @param {unknown} data — parsed JSON of a `.aperant/features/<area>.json`
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateAreaShape(data) {
+    const errors = [];
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        return { ok: false, errors: ['area file must be a JSON object'] };
+    }
+    if (!isNonEmptyString(data.area))
+        errors.push('area: required non-empty string');
+    if (!isNonEmptyString(data.route)) {
+        errors.push('route: required non-empty string — use "(cross-cutting)" for non-routed areas, never null');
+    }
+    if (data.components !== undefined) {
+        if (!Array.isArray(data.components)) {
+            errors.push('components: must be an array when present');
+        }
+        else {
+            for (const [i, c] of data.components.entries()) {
+                if (!isNonEmptyString(c))
+                    errors.push(`components[${i}]: must be a non-empty string`);
+            }
+        }
+    }
+    if (!isNonEmptyString(data.last_scanned) || !LAST_SCANNED_RE.test(data.last_scanned)) {
+        errors.push('last_scanned: must be a YYYY-MM-DD or full ISO 8601 date string');
+    }
+    if (!Array.isArray(data.features)) {
+        errors.push('features: required array');
+    }
+    else {
+        const seen = new Set();
+        for (const [i, group] of data.features.entries()) {
+            validateFeatureGroup(errors, `features[${i}]`, group);
+            const id = group?.id;
+            if (isNonEmptyString(id)) {
+                if (seen.has(id)) {
+                    errors.push(`features[${i}].id: duplicate feature id "${id}" in area`);
+                }
+                seen.add(id);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=area-shape.mjs.map

package/dist/cli/features/area-shape.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"area-shape.mjs","sourceRoot":"","sources":["../../../src/cli/features/area-shape.mjs"],"names":[],"mappings":"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"}

package/dist/cli/features/delta.d.mts

@@ -0,0 +1,78 @@
+/** Canonical JSON string per ID-17. No default-filling — hash what was written. */
+export function canonicalJson(value: any): string;
+/** sha256 hex over the canonical JSON of a value (entity hashing). */
+export function sha256Canonical(value: any): string;
+/** sha256 hex over raw bytes (delta file content, area file bytes). */
+export function sha256Bytes(data: any): string;
+/** expected_hash for a targeted entity — alias making the call sites read clearly. */
+export function hashEntity(entity: any): string;
+/**
+ * Shape + SEMANTIC ISO 8601 datetime validation (ST11). The regex alone
+ * accepted '2026-99-99T99:99:99Z' and '2026-02-30T12:00:00Z' — both could
+ * max-sort above real dates and stamp an invalid last_scanned. After the
+ * shape passes, the components are verified deterministically: month 1-12,
+ * a REAL calendar day via UTC round-trip (leap years included), hours<24,
+ * minutes<60, seconds<60 (offsets too).
+ */
+export function isValidIsoDatetime(value: any): boolean;
+/**
+ * Validate a parsed delta object. `mode: 'draft'` relaxes exactly two rules:
+ * the `needs-disposition` sentinel is allowed, and `area: null` is allowed
+ * (writer-must-assign). Everything else is identical.
+ *
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateDelta(delta: any, { mode }?: {
+    mode?: string | undefined;
+}): {
+    ok: boolean;
+    errors: string[];
+};
+/**
+ * Read + parse + validate a delta file. Never throws.
+ *
+ * @returns {{ ok: boolean, delta?: Record<string, any>, errors: string[], path: string }}
+ */
+export function parseDeltaFile(path: any, { mode }?: {
+    mode?: string | undefined;
+}): {
+    ok: boolean;
+    delta?: Record<string, any>;
+    errors: string[];
+    path: string;
+};
+/**
+ * Merge validated deltas per the ID-02 conflict matrix.
+ *
+ * @param {Array<{source: string, delta: object}>} sources — validated deltas
+ *   annotated with their file path (conflicts name BOTH writers).
+ * @param {{ getFeature: (area, featureId) => object|null,
+ *           getSubFeature: (area, featureId, subId) => object|null }} lookup
+ *   — reads against the CURRENT registry pre-image (rules e/f).
+ * @returns {{ ok: true, operations: Array<Record<string, any>>, files: Array<Record<string, any>> }
+ *         | { ok: false, conflicts: Array<{kind: string, message: string, sources: string[]}> }}
+ */
+export function mergeDeltas(sources: Array<{
+    source: string;
+    delta: object;
+}>, lookup: {
+    getFeature: (area: any, featureId: any) => object | null;
+    getSubFeature: (area: any, featureId: any, subId: any) => object | null;
+}): {
+    ok: true;
+    operations: Array<Record<string, any>>;
+    files: Array<Record<string, any>>;
+} | {
+    ok: false;
+    conflicts: Array<{
+        kind: string;
+        message: string;
+        sources: string[];
+    }>;
+};
+export const CHANGE_KINDS: readonly string[];
+export const DISPOSITIONS: readonly string[];
+/** Draft-only sentinel — NEVER valid at --write/--check time. */
+export const DRAFT_ONLY_DISPOSITION: "needs-disposition";
+export const OP_KINDS: readonly string[];
+//# sourceMappingURL=delta.d.mts.map

package/dist/cli/features/delta.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.mts","sourceRoot":"","sources":["../../../src/cli/features/delta.mjs"],"names":[],"mappings":"AAoFA,mFAAmF;AACnF,kDAEC;AAED,sEAAsE;AACtE,oDAEC;AAED,uEAAuE;AACvE,+CAEC;AAED,sFAAsF;AACtF,gDAEC;AASD;;;;;;;GAOG;AACH,wDAiBC;AAuBD;;;;;;GAMG;AACH;;IAFa;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA0K7C;AAED;;;;GAIG;AACH;;IAFa;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAiBxF;AAqDD;;;;;;;;;;GAUG;AACH,qCARW,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC,UAEtC;IAAE,UAAU,EAAE,CAAC,IAAI,KAAA,EAAE,SAAS,KAAA,KAAK,MAAM,GAAC,IAAI,CAAC;IAC7C,aAAa,EAAE,CAAC,IAAI,KAAA,EAAE,SAAS,KAAA,EAAE,KAAK,KAAA,KAAK,MAAM,GAAC,IAAI,CAAA;CAAE,GAExD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;CAAE,GACvF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC,CAAA;CAAE,CA8M/F;AAteD,6CAAsF;AACtF,6CAKE;AACF,iEAAiE;AACjE,qCAAsC,mBAAmB,CAAA;AACzD,yCAA6F"}