octwin-cli 0.8.5 → 0.8.7

package/dist/lib/declaration-check.js

@@ -17,11 +17,18 @@
  * checks that were catching real bugs. So the rule is: **report only what is
  * unambiguous, and walk away from anything else.**
  *
- * It reports exactly four things:
+ * It reports exactly five things:
  *   1. a key not in `properties` where `additionalProperties: false`
  *   2. a missing `required` key
  *   3. a scalar whose `type` is plainly wrong
  *   4. a value outside a closed `enum`
+ *   5. a map KEY outside `propertyNames` (`enum` or `pattern`)
+ *
+ * Rule 5 was added 2026-09-06 and is the reason the RBAC vocabulary is worth publishing at all: a
+ * map's keys carry meaning in `roles.yaml` (grant resource keys, verb keys), and reading only
+ * VALUES meant an author could not learn about a bad key until `--remote`. It is safe under the
+ * false-positive rule above because it is a faithful replay — the same enum membership and the same
+ * regex engine the platform's own Zod runs.
  *
  * It STOPS DESCENDING (reports nothing at all for that subtree) at any node
  * carrying `anyOf` / `oneOf` / `allOf` / `not`, at an unresolvable `$ref`, and at
@@ -142,6 +149,48 @@ function walk(value, schema, path, defs, out, file, depth) {
     const obj = value;
     const props = isObj(schema.properties) ? schema.properties : undefined;
     const addl = schema.additionalProperties;
+    // 5. KEY vocabulary — `propertyNames` on a map schema.
+    //
+    // The fifth rule, and the one this file existed without for its whole life. A map's KEYS carry
+    // meaning in three declarations (`roles.yaml` grants and verbs, `xrm.yaml` entity names), and the
+    // walker read only values — so a pack author following `craft/manifest.md` wrote `case:` where
+    // the key is `record.case`, passed offline `validate`, and learned the truth from a `--remote`
+    // round-trip that reported one bad guess at a time. They abandoned custom RBAC over it.
+    //
+    // Safe to report because it is a FAITHFUL REPLAY: the same `enum` membership and the same JS
+    // regex engine Zod itself runs, over a pattern the platform generated. A false positive would
+    // require the published schema to disagree with the platform that published it.
+    const names = isObj(schema.propertyNames) ? schema.propertyNames : undefined;
+    if (names) {
+        const allowed = Array.isArray(names.enum) ? names.enum : undefined;
+        const pattern = typeof names.pattern === 'string' ? names.pattern : undefined;
+        let re;
+        // A pattern the local engine cannot compile is out of subset, exactly like a combinator —
+        // walk away rather than guess. (JSON Schema permits ECMA-262; this IS that engine, so in
+        // practice only a future dialect change lands here.)
+        if (pattern) {
+            try {
+                re = new RegExp(pattern);
+            }
+            catch {
+                re = undefined;
+            }
+        }
+        for (const k of Object.keys(obj)) {
+            if (allowed && !allowed.includes(k)) {
+                out.push({
+                    file, path: path ? `${path}.${k}` : k,
+                    message: `not a valid key here — must be one of ${allowed.map(e => JSON.stringify(e)).join(', ')}`,
+                });
+            }
+            else if (re && !re.test(k)) {
+                out.push({
+                    file, path: path ? `${path}.${k}` : k,
+                    message: `not a valid key here — it must match ${pattern}`,
+                });
+            }
+        }
+    }
     // A map schema (`additionalProperties: <schema>`, no `properties`) — every
     // value shares one shape. This is how `entities:` and `agents:` are declared.
     if (!props && isObj(addl)) {

package/dist/lib/outcome.js

@@ -0,0 +1,79 @@
+/**
+ * `Outcome` — what one `octwin validate` check ACTUALLY did, as a value.
+ *
+ * ## Why this exists
+ *
+ * `cmdValidate` used to hand-write its own `✓` per check, inside the `if` that had the
+ * check's data, with a `skipped[]` array and a `skipReasons` Map maintained alongside. It
+ * was correct because someone was careful, and the next check added was one `if` away from
+ * lying again. It had lied before, twice, in the same shape:
+ *
+ *   - the KB-dependent block printed ONE `✓` above six checks whose own `✓`s lived inside
+ *     their `if`s, so a run with no pulled KB read as "one check, passed". An entire backlog
+ *     batch reached production that way;
+ *   - `yamlDocs()` parsed inside `try { … } catch { return [] }`, so a file that failed to
+ *     parse was silently DROPPED and every later check skipped it — `validate` printed
+ *     all-green over a pack the platform's importer then refused with the same message, from
+ *     the same `yaml` version this CLI already had.
+ *
+ * **An unparseable file is not "no findings", it is "no idea", and those must never print the
+ * same.** So a check no longer prints; it RETURNS one of three things, and a single printer
+ * renders all of them. A check that returns nothing cannot reach the `passed` branch, which
+ * makes the false-`✓` unrepresentable rather than merely discouraged.
+ *
+ * ## Why `not-run` carries the lookup rather than a message
+ *
+ * `describeKbLookup` phrases it at print time, so the wording lives in the module that owns
+ * the three KB states and cannot drift into a doubled "SKIPPED — SKIPPED —". It also lets the
+ * printer GROUP by reason: when the KB is absent every check skips for the identical reason,
+ * and six copies of one sentence is how a reader learns to scroll past the ⚠ block — the same
+ * failure as not printing it at all.
+ */
+import { describeKbLookup } from './kb-path.js';
+/**
+ * Run every check in order and print exactly what each returned.
+ *
+ * Returns the labels that could not run, so the caller can decide what a partial pass means
+ * (`--require-kb` fails on any; an interactive run says which, last, where it is read).
+ *
+ * The first `findings` outcome terminates via `die`, matching the previous behaviour: an
+ * author fixes one class at a time, and printing six screens of unrelated findings buries the
+ * first. Order therefore matters and is the caller's to choose.
+ */
+export function reportChecks(checks, io) {
+    const notRun = [];
+    for (const check of checks) {
+        const outcome = check.run();
+        switch (outcome.kind) {
+            case 'passed':
+                io.log(`✓ ${outcome.line}`);
+                break;
+            case 'findings': {
+                const n = outcome.lines.length;
+                io.err(`✗ ${n} ${outcome.noun}${n === 1 ? '' : 's'}:`);
+                for (const line of outcome.lines)
+                    io.err(`  ✗ ${line}`);
+                io.die(outcome.hint);
+            }
+            // eslint-disable-next-line no-fallthrough -- `die` returns never; the case above cannot exit.
+            case 'not-run':
+                notRun.push({ label: check.label, lookup: outcome.lookup });
+                break;
+        }
+    }
+    // One ⚠ per distinct reason, naming every check it cost. Grouped by the lookup's IDENTITY.
+    const byReason = new Map();
+    for (const { label, lookup } of notRun) {
+        const key = lookup.state === 'ok'
+            ? 'ok'
+            : `${lookup.state}|${'dir' in lookup ? lookup.dir : ''}|${'reason' in lookup ? lookup.reason : ''}`;
+        const bucket = byReason.get(key) ?? { lookup, labels: [] };
+        bucket.labels.push(label);
+        byReason.set(key, bucket);
+    }
+    for (const { lookup, labels } of byReason.values()) {
+        const what = labels.length === 1 ? labels[0] : `${labels.length} checks (${labels.join(', ')})`;
+        io.log(`⚠ ${describeKbLookup(lookup, what)}`);
+    }
+    return notRun.map(n => n.label);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {