@pikku/core 0.12.136 → 0.12.137

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.12.137
+
+### Patch Changes
+
+- 0c865d9: Changes and changesets replace milestones. The changes commands run on a local queue when the checkout has no fabric project; `pikku changes next` routes to a changes, upgrade or knowledge agent and merges finished changesets. A changeset that creates or alters a table, or has 6 or more changes, needs a plan at `knowledge/plans/<changeset>.plan.json` (anything else goes to an optional judge at `PIKKU_PLAN_JUDGE_URL`), and `changes done` holds it to that plan. `pikku knowledge gaps` replaces `knowledge next`/`reconcile`, and also reports code a merged plan built that is gone and notes that were deleted.
+- c36b066: Scenario coverage moves into OSS. `@pikku/core/scenario/coverage` adds `readScenarioCoverage`, which reports the lines no scenario reaches, the mutations no scenario drives, and the pages scenarios open. It is exposed through `pikku scenario coverage`, `console:getScenarioCoverage`, and a "Not tested by any scenario" card on the Scenarios page. `LocalMetaService.getRpcMeta` now reads the `.internal.gen.json` file that codegen actually writes.
+- 0963b73: Every scope tree now records where it came from: `origin` on `ScopeDefinitionMeta` is `{ kind: 'app' }` for the app's own `defineScope`, `{ kind: 'generated' }` for a tree the CLI wrote into the project (a `.gen.ts`, or the `app` root derived from personas), and `{ kind: 'addon', package, displayName }` for one an installed addon declared. An addon's build stamps its own package and display name on its trees, and the host keeps that name while recording the package it actually installed. `MetaService.getScopesMeta()` reads the result, and the console's all-meta payload carries it as `scopes`.
+
+  The console's Scopes page becomes **Permissions** and is grouped by that origin: the app's own permissions first, then what Pikku generated into the project, then one card per addon (Pikku's own before third-party, each alphabetical), each card folding to its header — the app's own starts open, every addon's starts folded, and any search or filter opens them all. Above the cards, two filters narrow the page to what one role is given (or to what no role is given yet) and to one source. A permission group no longer says "Not part of any role yet" above lines that are each given to a role.
+
 ## 0.12.136
 
 ### Patch Changes

package/dist/services/meta-service.d.ts

@@ -10,6 +10,7 @@ import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js';
 import type { ResolvedPersona } from './personas-service.js';
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { FeatureFlagDefinitionsMeta } from '../wirings/flag/flag.types.js';
+import type { ScopeDefinitionsMeta } from '../wirings/scope/scope.types.js';
 import type { AnalyticsEventsMeta } from '../analytics/analytics.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
@@ -156,6 +157,14 @@ export interface MetaService {
      * seed granted from rather than a second one.
      */
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    /**
+     * The scope trees declared with `defineScope`, keyed by root, each carrying
+     * where it came from.
+     *
+     * The scope store holds the grantable ids; this holds what the store does
+     * not — a root's display name and which addon, if any, declared it.
+     */
+    getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     /**
      * The flags declared with `defineFeatureFlags`, keyed by name.
      *
@@ -199,6 +208,7 @@ export declare class LocalMetaService implements MetaService {
     private workflowMetaCache;
     private personasMetaCache;
     private systemRolesMetaCache;
+    private scopesMetaCache;
     private featureFlagsMetaCache;
     private analyticsMetaCache;
     private featuresMetaCache;
@@ -236,6 +246,7 @@ export declare class LocalMetaService implements MetaService {
     getWorkflowMeta(): Promise<WorkflowsMeta>;
     getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     getFeatureFlagsMeta(): Promise<FeatureFlagDefinitionsMeta>;
     getAnalyticsMeta(): Promise<AnalyticsEventsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;

package/dist/services/meta-service.js

@@ -16,6 +16,7 @@ export class LocalMetaService {
     workflowMetaCache = null;
     personasMetaCache = null;
     systemRolesMetaCache = null;
+    scopesMetaCache = null;
     featureFlagsMetaCache = null;
     analyticsMetaCache = null;
     featuresMetaCache = null;
@@ -115,6 +116,7 @@ export class LocalMetaService {
         this.workflowMetaCache = null;
         this.personasMetaCache = null;
         this.systemRolesMetaCache = null;
+        this.scopesMetaCache = null;
         this.featureFlagsMetaCache = null;
         this.analyticsMetaCache = null;
         this.featuresMetaCache = null;
@@ -216,7 +218,7 @@ export class LocalMetaService {
         if (this.rpcMetaCache)
             return this.rpcMetaCache;
         try {
-            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.gen.json');
+            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.internal.gen.json');
             this.rpcMetaCache = content ? JSON.parse(content) : {};
             return this.rpcMetaCache;
         }
@@ -278,6 +280,13 @@ export class LocalMetaService {
         this.systemRolesMetaCache = content ? JSON.parse(content) : {};
         return this.systemRolesMetaCache;
     }
+    async getScopesMeta() {
+        if (this.scopesMetaCache)
+            return this.scopesMetaCache;
+        const content = await this.readFile('scopes/pikku-scopes-meta.gen.json');
+        this.scopesMetaCache = content ? JSON.parse(content) : {};
+        return this.scopesMetaCache;
+    }
     async getFeatureFlagsMeta() {
         if (this.featureFlagsMetaCache)
             return this.featureFlagsMetaCache;

package/dist/wirings/persona/persona-app-scopes.js

@@ -57,5 +57,6 @@ export const buildAppScopeDefinition = (personas) => {
         displayName: 'Apps',
         description: 'Which frontend a person may sign in to',
         scopes,
+        origin: { kind: 'generated' },
     };
 };

package/dist/wirings/scope/index.d.ts

@@ -1,4 +1,4 @@
 export { defineScope } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
-export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, } from './scope.types.js';
+export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, ScopeOrigin, } from './scope.types.js';
 export { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/scope/scope.types.d.ts

@@ -21,12 +21,26 @@ export type ScopeNodeMeta = {
     description?: string;
     scopes?: Record<string, ScopeNodeMeta>;
 };
+/**
+ * Who put a scope tree into the app: the app's own `defineScope`, a file the
+ * CLI generated into the project, or an installed addon.
+ */
+export type ScopeOrigin = {
+    kind: 'app';
+} | {
+    kind: 'generated';
+} | {
+    kind: 'addon';
+    package: string;
+    displayName?: string;
+};
 export type ScopeDefinitionMeta = {
     name: string;
     displayName?: string;
     description?: string;
     scopes?: Record<string, ScopeNodeMeta>;
     sourceFile?: string;
+    origin?: ScopeOrigin;
 };
 export type ScopeDefinitions = ScopeDefinitionMeta[];
 export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>;

package/dist/wirings/scope/validate-scope-definitions.js

@@ -67,6 +67,7 @@ export function validateAndBuildScopeDefinitionsMeta(definitions) {
             description: def.description,
             scopes: def.scopes,
             sourceFile: def.sourceFile,
+            origin: def.origin,
         };
     }
     return meta;

package/dist/wirings/workflow/scenario-coverage.d.ts

@@ -0,0 +1,70 @@
+import type { MetaService } from '../../services/meta-service.js';
+/** Per-function line coverage as `pikku scenario run --coverage` records it. */
+export interface ScenarioFunctionCoverage {
+    name: string;
+    sourceFile: string;
+    status: 'covered' | 'partial' | 'uncovered' | 'unknown';
+    totalLines: number;
+    missedLines: number[];
+}
+/** The file `pikku scenario run --coverage` writes to `.pikku/coverage/scenario-coverage.json`. */
+export interface ScenarioCoverageFile {
+    generatedAt: string;
+    environment: string;
+    scenarios: Record<string, {
+        functions?: ScenarioFunctionCoverage[];
+        summary?: {
+            total?: number;
+        };
+    }>;
+}
+/** A function with lines no scenario reaches. */
+export interface ScenarioCoverageGap {
+    function: string;
+    sourceFile: string;
+    status: 'uncovered' | 'partial';
+    /** Collapsed line ranges, e.g. `["L14-31", "L42"]`. */
+    missing: string[];
+    missedLines: number;
+    totalLines: number;
+}
+/** A mutation a user can perform that no scenario drives. */
+export interface UncoveredMutation {
+    id: string;
+    sourceFile?: string;
+}
+export interface ScenarioCoverage {
+    /** Line coverage across every scenario; `null` until a run with `--coverage` has been recorded. */
+    api: {
+        generatedAt: string;
+        environment: string;
+        pct: number;
+        covered: number;
+        total: number;
+        gaps: ScenarioCoverageGap[];
+    } | null;
+    mutations: {
+        required: number;
+        covered: number;
+        uncovered: UncoveredMutation[];
+    };
+    /** Paths a scenario opens; `unvisited` only when the caller knows the app's routes. */
+    routes: {
+        visited: string[];
+        total: number | null;
+        unvisited: string[] | null;
+    };
+}
+/** Lines no scenario reaches, per function: a line counts as covered if any scenario hit it. */
+export declare function aggregateScenarioCoverageGaps(file: ScenarioCoverageFile): ScenarioCoverageGap[];
+/**
+ * Everything a scenario measures about the app, read from the meta codegen and
+ * `pikku scenario run --coverage` leave in `.pikku`.
+ *
+ * A mutation is a function a user changes something with: a mutating HTTP
+ * route, or an exposed RPC whose name opens with a mutating verb. Only RPCs a
+ * scenario can drive are required.
+ */
+export declare function readScenarioCoverage(metaService: MetaService, { routes }?: {
+    routes?: string[];
+}): Promise<ScenarioCoverage>;

package/dist/wirings/workflow/scenario-coverage.js

@@ -0,0 +1,159 @@
+const MUTATING_METHODS = new Set(['post', 'put', 'patch', 'delete']);
+const MUTATING_VERB = /^(create|add|new|update|edit|set|change|rename|delete|remove|destroy|archive|restore|assign|unassign|submit|approve|reject|cancel|complete|start|stop|send|invite|upload|register|book|reserve|claim|join|leave|mark|toggle|move|reorder|import|apply|save|record|log|generate|grant|revoke|link|unlink|publish|unpublish|enable|disable|accept|decline|resend|retry|sync|trigger|run|provision|deploy|purchase|checkout|pay|refund|subscribe|unsubscribe|reset|confirm|rotate|attach|detach|duplicate|clone|merge|split|schedule|reschedule|dispatch|finish|close|reopen|promote|demote|transfer|swap|seed|clear|cleanup|refresh|rebuild|install|uninstall|connect|disconnect|activate|deactivate|block|unblock|pin|unpin|vote|rate|comment|reply|post)([A-Z0-9]|$)/;
+const NAVIGATION_STEPS = new Set(['opensPage']);
+const isFrameworkTagged = (tags) => (tags ?? []).some((tag) => tag === 'pikku' || tag.startsWith('pikku:'));
+const isGenerated = (sourceFile) => /\.gen\.ts$/.test(sourceFile ?? '');
+const normalisePath = (path) => path.replace(/\/+$/, '') || '/';
+const pct = (covered, total) => total === 0 ? 100 : Math.round((covered / total) * 100);
+function collapseRanges(lines) {
+    const sorted = [...new Set(lines)].sort((a, b) => a - b);
+    const ranges = [];
+    for (let i = 0; i < sorted.length;) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        ranges.push(sorted[i] === sorted[j] ? `L${sorted[i]}` : `L${sorted[i]}-${sorted[j]}`);
+        i = j + 1;
+    }
+    return ranges;
+}
+/** Lines no scenario reaches, per function: a line counts as covered if any scenario hit it. */
+export function aggregateScenarioCoverageGaps(file) {
+    const byFunction = new Map();
+    for (const report of Object.values(file.scenarios ?? {})) {
+        for (const fn of report.functions ?? []) {
+            if (fn.status === 'unknown' || fn.totalLines === 0)
+                continue;
+            let entry = byFunction.get(fn.name);
+            if (!entry) {
+                entry = {
+                    sourceFile: fn.sourceFile,
+                    missed: null,
+                    total: fn.totalLines,
+                };
+                byFunction.set(fn.name, entry);
+            }
+            const missed = new Set(fn.missedLines);
+            entry.missed =
+                entry.missed === null
+                    ? missed
+                    : new Set([...entry.missed].filter((line) => missed.has(line)));
+        }
+    }
+    const gaps = [];
+    for (const [name, entry] of byFunction) {
+        if (!entry.missed || entry.missed.size === 0)
+            continue;
+        const missed = [...entry.missed];
+        gaps.push({
+            function: name,
+            sourceFile: entry.sourceFile,
+            status: missed.length >= entry.total ? 'uncovered' : 'partial',
+            missing: collapseRanges(missed),
+            missedLines: missed.length,
+            totalLines: entry.total,
+        });
+    }
+    return gaps.sort((a, b) => (a.status === b.status ? 0 : a.status === 'uncovered' ? -1 : 1) ||
+        b.missedLines - a.missedLines ||
+        a.function.localeCompare(b.function));
+}
+function scenarioNodes(workflows) {
+    return Object.values(workflows).flatMap((meta) => {
+        const workflow = meta;
+        return workflow?.source === 'scenario'
+            ? Object.values(workflow.nodes ?? {})
+            : [];
+    });
+}
+/**
+ * Everything a scenario measures about the app, read from the meta codegen and
+ * `pikku scenario run --coverage` leave in `.pikku`.
+ *
+ * A mutation is a function a user changes something with: a mutating HTTP
+ * route, or an exposed RPC whose name opens with a mutating verb. Only RPCs a
+ * scenario can drive are required.
+ */
+export async function readScenarioCoverage(metaService, { routes } = {}) {
+    const [functions, http, rpc, workflows, coverageFile] = await Promise.all([
+        metaService.getFunctionsMeta(),
+        metaService.getHttpMeta(),
+        metaService.getRpcMeta(),
+        metaService.getWorkflowMeta(),
+        metaService.readFile('coverage/scenario-coverage.json'),
+    ]);
+    const nodes = scenarioNodes(workflows);
+    const driven = new Set(nodes.map((node) => node?.rpcName).filter((name) => !!name));
+    const visited = [
+        ...new Set(nodes
+            .filter((node) => node?.rpcName && NAVIGATION_STEPS.has(node.rpcName))
+            .map((node) => node.input?.['path'])
+            .filter((path) => typeof path === 'string')
+            .map(normalisePath)),
+    ].sort();
+    const invocable = new Set(Object.keys(rpc));
+    const required = new Map();
+    for (const [id, meta] of Object.entries(functions)) {
+        const funcId = meta.pikkuFuncId ?? id;
+        if (meta.functionType && meta.functionType !== 'user')
+            continue;
+        if (meta.expose === false || meta.readonly === true)
+            continue;
+        if (!MUTATING_VERB.test(funcId))
+            continue;
+        if (isFrameworkTagged(meta.tags) || isGenerated(meta.sourceFile))
+            continue;
+        if (!invocable.has(funcId))
+            continue;
+        required.set(funcId, meta.sourceFile);
+    }
+    for (const [method, wirings] of Object.entries(http)) {
+        if (!MUTATING_METHODS.has(method.toLowerCase()))
+            continue;
+        for (const route of Object.values(wirings ?? {})) {
+            const funcId = route?.pikkuFuncId;
+            if (!funcId || !invocable.has(funcId))
+                continue;
+            if (isFrameworkTagged(route.tags))
+                continue;
+            const sourceFile = functions[funcId]?.sourceFile;
+            if (isGenerated(sourceFile))
+                continue;
+            required.set(funcId, sourceFile);
+        }
+    }
+    const uncovered = [...required]
+        .filter(([id]) => !driven.has(id))
+        .map(([id, sourceFile]) => (sourceFile ? { id, sourceFile } : { id }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    let api = null;
+    if (coverageFile) {
+        const file = JSON.parse(coverageFile);
+        const total = Object.values(file.scenarios ?? {}).reduce((most, one) => Math.max(most, one?.summary?.total ?? 0), 0);
+        if (total > 0) {
+            const gaps = aggregateScenarioCoverageGaps(file);
+            api = {
+                generatedAt: file.generatedAt,
+                environment: file.environment,
+                total,
+                covered: total - gaps.length,
+                pct: pct(total - gaps.length, total),
+                gaps,
+            };
+        }
+    }
+    const known = routes ? [...new Set(routes.map(normalisePath))].sort() : null;
+    return {
+        api,
+        mutations: {
+            required: required.size,
+            covered: required.size - uncovered.length,
+            uncovered,
+        },
+        routes: {
+            visited,
+            total: known ? known.length : null,
+            unvisited: known ? known.filter((path) => !visited.includes(path)) : null,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.136",
+  "version": "0.12.137",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -39,6 +39,7 @@
     "./channel": "./dist/wirings/channel/index.js",
     "./workflow": "./dist/wirings/workflow/index.js",
     "./scenario": "./dist/wirings/workflow/pikku-scenario-service.js",
+    "./scenario/coverage": "./dist/wirings/workflow/scenario-coverage.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
     "./actor-flow": "./dist/wirings/actor-flow/index.js",

package/src/public-surface.json

@@ -99,6 +99,10 @@
     "resolveFeatureScenarios",
     "resolveScenarioSurfaces"
   ],
+  "./scenario/coverage": [
+    "aggregateScenarioCoverageGaps",
+    "readScenarioCoverage"
+  ],
   "./workflow/timeline": [
     "buildRunTimeline",
     "reconstructFinalState",