@shanyucoder/flowgrid 0.1.0

package/dist/graph/types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared types for artifactgraph.
+ *
+ * Mental model (DSL loop):
+ * - Product repo git = SSOT — registries/*.json, codegen/templates, specs, skills/docs
+ * - MCP = index + protocol only — .artifactgraph/index.db, allowlisted gen, grill/parity remember
+ * - MCP does NOT own or rewrite registry SSOT; promote stays in product docs/skills
+ * - Cloud LLM = only low-confidence gaps (cloudPromptSlice)
+ */
+/** One missing / suggested artifact the agent or member should resolve. */
+export type GapKind = 'needs-component' | 'needs-ui' | 'needs-common' | 'needs-unit-test' | 'needs-e2e'
+/** Alias-oriented: missing testcase YAML / e2e bundle (prefer needs-e2e when registry miss). */
+ | 'needs-testcase' | 'missing-hashtag' | 'missing-codegen-profile' | 'registry-miss' | 'handoff'
+/** Cross-surface drift: create≠edit validate, null vs '', FE≠BE, … */
+ | 'parity-drift'
+/**
+ * Action data-scope ≠ screen display data.
+ * Screen shows hotel+rooms; btn (any kind) exports/sends/processes order data → warn.
+ */
+ | 'context-orphan'
+/**
+ * Duplicate URI path across specs without #reuse-api — structural conflict before merging.
+ * Rule: if 2 specs define the exact same URI+method without #reuse-api → blocking warning.
+ */
+ | 'duplicate-api-route'
+/**
+ * Docs hub business-fact gap (`#missing_info`). Do not invent fills — grill / member confirm
+ * before writing product SSOT.
+ */
+ | 'missing-info';
+export interface Gap {
+    kind: GapKind;
+    /** Human-readable summary (safe to put in a cloud prompt). */
+    message: string;
+    /** Suggested hashtag, e.g. "#needs-component: cell-status:MoStatusChip:label" */
+    suggestedTag?: string;
+    /** Where it was found (spec path, handoff path, bullet line…). */
+    source?: string;
+    severity: 'info' | 'warn' | 'error';
+    /** 0–1: high = local MCP can apply without cloud. */
+    confidence: number;
+    /** Machine id for remember / parity (e.g. password.min). */
+    id?: string;
+}
+/** How empty values are represented on one surface. */
+export type EmptyPolicy = 'null' | 'empty-string' | 'omit' | 'empty-array' | 'unknown';
+/**
+ * One field observation on one surface (create / edit / api.update / …).
+ * Produced by local scan of legacy.fields OR by cloud archaeology (same schema).
+ */
+export interface ParityObservation {
+    surface: string;
+    required?: boolean;
+    type?: string;
+    empty?: EmptyPolicy;
+    /** Fingerprintable rules: min, max, regex, email, … */
+    rules?: Record<string, unknown>;
+    source?: string;
+}
+/** Structured finding — cloud MUST return this shape in the same archaeology turn. */
+export interface ParityFinding {
+    id: string;
+    field: string;
+    surfaces: string[];
+    observed: ParityObservation[];
+    severity?: 'info' | 'warn' | 'error';
+    /** Optional A/B/C options; local synthesizes defaults if missing. */
+    options?: Array<{
+        choice: 'A' | 'B' | 'C';
+        label: string;
+        canon?: Record<string, unknown>;
+    }>;
+    askUser?: string;
+}
+/**
+ * Screen shows dataset A (primary + related visible on UI).
+ * Action uses dataset B — if B ⊄ A → context-orphan (independent of btn label).
+ */
+export interface ContextOrphanFinding {
+    id: string;
+    hostSurface: string;
+    /** Data the screen actually displays (primary entity + child/related rows on UI). */
+    screenData: string[];
+    action: {
+        id: string;
+        label?: string;
+        kind?: string;
+        /** Data the action reads/writes/exports/sends — must be subset of screenData when in-scope. */
+        usesData: string[];
+    };
+    reason?: string;
+    severity?: 'info' | 'warn' | 'error';
+    options?: Array<{
+        choice: 'A' | 'B' | 'C';
+        label: string;
+    }>;
+    askUser?: string;
+    source?: string;
+}
+/** Result of local analyze (spec path and/or bullet text). */
+export interface AnalyzeResult {
+    projectId?: string;
+    repoRoot: string;
+    specPath?: string;
+    /** Tags already on the spec (or drafted from bullets). */
+    tags: string[];
+    /** Draft tags suggested from bullets / registry match — not yet written. */
+    draftTags: string[];
+    gaps: Gap[];
+    /** Short questions for member confirm (grill A/B/C style). */
+    askUser: string[];
+    /** Compact blob intended for cloud — only unresolved low-confidence gaps. */
+    cloudPromptSlice: string;
+}
+/** One DSL lane: which registry/templates/gen keys/tags belong together (documentation for agents). */
+export interface DslLane {
+    /** Path(s) under product repo — SSOT stays there. */
+    registries?: string[];
+    templates?: string;
+    /** Keys in artifactgraph.json commands for local gen. */
+    genKeys: string[];
+    /** Standard needs-* / phase tags agents should prefer. */
+    needsTags?: string[];
+    /** Short note for status / cloudPromptSlice. */
+    note?: string;
+}
+/**
+ * Optional map of lanes (fe / be / unit / e2e / docs).
+ * Does not store registry payloads — only pointers + gen keys for MCP index/protocol.
+ */
+export interface DslManifest {
+    /** Always product-repo: registries + hbs live outside this MCP package. */
+    ssot: 'product-repo';
+    lanes: Record<string, DslLane>;
+}
+/** @deprecated Legacy external hub ids; standalone runtime does not resolve them. */
+export interface ArtifactgraphHubs {
+    docs?: string;
+    tests?: string;
+}
+/**
+ * Project-relative lexicon paths for MCP suggest — NOT registry SSOT.
+ * Init writes these under artifactgraph/lexicon/.
+ */
+export interface ArtifactgraphVocabularies {
+    /** R2.1 — UI/API/mark DSL tag lexicon */
+    registryTags?: string;
+    /** R3.1 — E2E taxonomy lexicon */
+    testTaxonomy?: string;
+}
+/** artifactgraph.json living in a product repo (brownfield wire). */
+export interface ArtifactgraphConfig {
+    version?: number;
+    stack: string;
+    mode: 'brownfield' | 'greenfield';
+    projectId?: string;
+    commands: Record<string, string[]>;
+    registries: string[];
+    gapSources?: string[];
+    specRoots?: string[];
+    /**
+     * Glob patterns for OpenAPI / backend-spec YAML files to index as API routes.
+     * Defaults: derived from specRoots by matching **\/{01-backend-spec,02-openapi}.yaml.
+     * Example: ["surfaces/**\/code\/**\/01-backend-spec.yaml"]
+     */
+    apiSpecRoots?: string[];
+    /** @deprecated Standalone runtime ignores external hubs. */
+    hubs?: ArtifactgraphHubs;
+    /** Lexicon file paths for suggest_tags / draftTags (local index). */
+    vocabularies?: ArtifactgraphVocabularies;
+    templates?: {
+        root: string;
+        engine: string;
+    };
+    /** Lane index metadata — optional; MCP rebuild still reads `registries[]`. */
+    dsl?: DslManifest;
+}
+/** Skill allowlist for one harness sync profile (full | shared | docs | tests | tooling). */
+export interface PlatformHarnessProfile {
+    groups?: string[];
+    skills?: string[];
+    note?: string;
+}
+export interface PlatformHarnessSyncPolicy {
+    /** propose = report drift only; never wipe other lanes blindly */
+    mode?: 'propose' | 'apply';
+    description?: string;
+}
+export interface PlatformHarness {
+    defaultByRole?: Record<string, string>;
+    profiles?: Record<string, PlatformHarnessProfile>;
+    syncPolicy?: PlatformHarnessSyncPolicy;
+}
+export interface PlatformProject {
+    root: string;
+    role: string;
+    stack: string;
+    repo: string;
+    description?: string;
+    /** Override harness.defaultByRole — full | shared | docs | tests | tooling */
+    harnessProfile?: string;
+}
+export interface PlatformReposMap {
+    workspaceRoot: string;
+    defaultGroup: string;
+    harness?: PlatformHarness;
+    projects: Record<string, PlatformProject>;
+}

package/dist/graph/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types for artifactgraph.
+ *
+ * Mental model (DSL loop):
+ * - Product repo git = SSOT — registries/*.json, codegen/templates, specs, skills/docs
+ * - MCP = index + protocol only — .artifactgraph/index.db, allowlisted gen, grill/parity remember
+ * - MCP does NOT own or rewrite registry SSOT; promote stays in product docs/skills
+ * - Cloud LLM = only low-confidence gaps (cloudPromptSlice)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/test/config/project-root.d.ts

@@ -0,0 +1,5 @@
+export type FlowGridTestLane = 'tests' | 'fe';
+export declare function packageRoot(): string;
+export declare function packageVersion(): string;
+export declare function resolveProjectRoot(explicit?: string): string;
+export declare function enginePath(...parts: string[]): string;

package/dist/test/config/project-root.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+function envFirst(...keys) {
+    for (const key of keys) {
+        const value = process.env[key];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+export function packageRoot() {
+    return pkgRoot;
+}
+export function packageVersion() {
+    return JSON.parse(readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'))
+        .version ?? '0.0.0';
+}
+export function resolveProjectRoot(explicit) {
+    const root = path.resolve(explicit ?? envFirst('FLOWGRID_PROJECT_ROOT') ?? process.cwd());
+    if (!existsSync(root))
+        throw new Error(`FlowGrid test project root not found: ${root}`);
+    return root;
+}
+export function enginePath(...parts) {
+    return path.join(pkgRoot, 'engines', ...parts);
+}
+//# sourceMappingURL=project-root.js.map

package/dist/test/config/project-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-root.js","sourceRoot":"","sources":["../../../src/test/config/project-root.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;AAInF,SAAS,QAAQ,CAAC,GAAG,IAAc;IACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,KAAK;YAAE,OAAO,KAAK,CAAA;IACzB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAQ,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAA0B;SAClG,OAAO,IAAI,OAAO,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAiB;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CACvB,QAAQ,IAAI,QAAQ,CAAC,uBAAuB,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAC/D,CAAA;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,EAAE,CAAC,CAAA;IACvF,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAG,KAAe;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,CAAA;AAChD,CAAC"}

package/dist/test/engines/run.d.ts

@@ -0,0 +1,10 @@
+export declare function runEngine(opts: {
+    engineRel: string[];
+    projectRoot: string;
+    argv?: string[];
+    env?: Record<string, string>;
+}): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};

package/dist/test/engines/run.js

@@ -0,0 +1,16 @@
+import { spawnSync } from 'node:child_process';
+import { enginePath } from '../config/project-root.js';
+export function runEngine(opts) {
+    const engine = enginePath(...opts.engineRel);
+    const result = spawnSync(process.execPath, [engine, ...(opts.argv ?? [])], {
+        cwd: opts.projectRoot,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            FLOWGRID_PROJECT_ROOT: opts.projectRoot,
+            ...opts.env,
+        },
+    });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+//# sourceMappingURL=run.js.map

package/dist/test/engines/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/test/engines/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAEtD,MAAM,UAAU,SAAS,CAAC,IAKzB;IACC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE;QACzE,GAAG,EAAE,IAAI,CAAC,WAAW;QACrB,QAAQ,EAAE,MAAM;QAChB,GAAG,EAAE;YACH,GAAG,OAAO,CAAC,GAAG;YACd,qBAAqB,EAAE,IAAI,CAAC,WAAW;YACvC,GAAG,IAAI,CAAC,GAAG;SACZ;KACF,CAAC,CAAA;IACF,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAA;AAC5F,CAAC"}

package/dist/test/mcp/tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTools(server: McpServer): void;

package/dist/test/mcp/tools.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { resolveProjectRoot } from '../config/project-root.js';
+import { runEngine } from '../engines/run.js';
+function text(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+const shape = {
+    projectRoot: z.string().optional(),
+    testsDocs: z.string().optional(),
+    docsRoot: z.string().optional(),
+    argv: z.array(z.string()).optional(),
+};
+export function registerTools(server) {
+    const make = (engineRel, dryRun = false) => async (input) => {
+        try {
+            const argv = [...(input.argv ?? [])];
+            if (dryRun && !argv.includes('--dry-run'))
+                argv.push('--dry-run');
+            const env = {};
+            if (input.testsDocs)
+                env.FLOWGRID_TESTS_DOC = input.testsDocs;
+            if (input.docsRoot)
+                env.FLOWGRID_DOCS_ROOT = input.docsRoot;
+            const result = runEngine({
+                engineRel,
+                projectRoot: resolveProjectRoot(input.projectRoot),
+                argv,
+                env,
+            });
+            return text({ ok: result.status === 0, ...result });
+        }
+        catch (error) {
+            return text({ ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    server.tool('cases_render', 'Render plan YAML to Markdown on the tests hub.', shape, make(['cases', 'render-cases.mjs']));
+    server.tool('cases_check_plans', 'Validate plan YAML structure.', shape, make(['cases', 'check-plans.mjs']));
+    server.tool('cases_check_coverage', 'Check plan coverage gaps.', shape, make(['cases', 'check-coverage.mjs']));
+    server.tool('testcase_gen', 'Generate Playwright tests on an FE repo from plan YAML.', shape, make(['testcase', 'runners', 'generate.mjs']));
+    server.tool('testcase_gen_dry', 'Dry-run Playwright generation from plan YAML.', shape, make(['testcase', 'runners', 'generate.mjs'], true));
+    server.tool('e2e_registry_validate', 'Validate FE e2e-test registry.', shape, make(['testcase', 'runners', 'validate-registry.mjs']));
+}
+//# sourceMappingURL=tools.js.map

package/dist/test/mcp/tools.js.map

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

package/dist/test/optional/fallback-evidence.d.ts

@@ -0,0 +1,34 @@
+export declare const OPTIONAL_FALLBACK_SCHEMA_VERSION: "1.0.0";
+export declare const OPTIONAL_FALLBACK_EVENT: "flowgrid.missing-optional";
+export declare const FLOWGRID_TEST_PACKAGE: "@platform/flowgrid-test";
+export type OptionalFallbackReason = 'not-configured' | 'unavailable' | 'invocation-failed';
+export type OptionalFallbackMode = 'local-deterministic-coverage' | 'local-deterministic-search';
+export interface ReadMetrics {
+    fileReads: number;
+    contextBytes: number;
+}
+export interface MissingOptionalEvent {
+    schemaVersion: typeof OPTIONAL_FALLBACK_SCHEMA_VERSION;
+    event: typeof OPTIONAL_FALLBACK_EVENT;
+    package: typeof FLOWGRID_TEST_PACKAGE;
+    runId: string;
+    optional: string;
+    reason: OptionalFallbackReason;
+    fallback: OptionalFallbackMode;
+    metrics: ReadMetrics;
+}
+export type MissingOptionalInput = Omit<MissingOptionalEvent, 'schemaVersion' | 'event' | 'package'>;
+export declare function validateMissingOptionalEvent(value: unknown): {
+    ok: boolean;
+    errors: string[];
+};
+export declare class ReadMeasurement {
+    #private;
+    read(file: string): Buffer;
+    readText(file: string): string;
+    snapshot(): ReadMetrics;
+}
+export declare class MissingOptionalEventEmitter {
+    #private;
+    emit(input: MissingOptionalInput): MissingOptionalEvent | null;
+}

package/dist/test/optional/fallback-evidence.js

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+export const OPTIONAL_FALLBACK_SCHEMA_VERSION = '1.0.0';
+export const OPTIONAL_FALLBACK_EVENT = 'flowgrid.missing-optional';
+export const FLOWGRID_TEST_PACKAGE = '@platform/flowgrid-test';
+function isNonNegativeInteger(value) {
+    return Number.isInteger(value) && Number(value) >= 0;
+}
+export function validateMissingOptionalEvent(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return { ok: false, errors: ['event must be an object'] };
+    }
+    const event = value;
+    const errors = [];
+    const allowed = new Set([
+        'schemaVersion',
+        'event',
+        'package',
+        'runId',
+        'optional',
+        'reason',
+        'fallback',
+        'metrics',
+    ]);
+    for (const key of Object.keys(event)) {
+        if (!allowed.has(key))
+            errors.push(`unexpected field: ${key}`);
+    }
+    if (event.schemaVersion !== OPTIONAL_FALLBACK_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be ${OPTIONAL_FALLBACK_SCHEMA_VERSION}`);
+    }
+    if (event.event !== OPTIONAL_FALLBACK_EVENT) {
+        errors.push(`event must be ${OPTIONAL_FALLBACK_EVENT}`);
+    }
+    if (event.package !== FLOWGRID_TEST_PACKAGE) {
+        errors.push(`package must be ${FLOWGRID_TEST_PACKAGE}`);
+    }
+    if (typeof event.runId !== 'string' || event.runId.length === 0) {
+        errors.push('runId must be a non-empty string');
+    }
+    if (typeof event.optional !== 'string' || event.optional.length === 0) {
+        errors.push('optional must be a non-empty string');
+    }
+    if (!['not-configured', 'unavailable', 'invocation-failed'].includes(String(event.reason))) {
+        errors.push('reason is invalid');
+    }
+    if (!['local-deterministic-coverage', 'local-deterministic-search'].includes(String(event.fallback))) {
+        errors.push('fallback is invalid');
+    }
+    if (typeof event.metrics !== 'object' || event.metrics === null || Array.isArray(event.metrics)) {
+        errors.push('metrics must be an object');
+    }
+    else {
+        const metrics = event.metrics;
+        if (!isNonNegativeInteger(metrics.fileReads)) {
+            errors.push('metrics.fileReads must be a non-negative integer');
+        }
+        if (!isNonNegativeInteger(metrics.contextBytes)) {
+            errors.push('metrics.contextBytes must be a non-negative integer');
+        }
+        for (const key of Object.keys(metrics)) {
+            if (!['fileReads', 'contextBytes'].includes(key)) {
+                errors.push(`unexpected metrics field: ${key}`);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+export class ReadMeasurement {
+    #metrics = { fileReads: 0, contextBytes: 0 };
+    read(file) {
+        const content = readFileSync(file);
+        this.#metrics.fileReads += 1;
+        this.#metrics.contextBytes += content.byteLength;
+        return content;
+    }
+    readText(file) {
+        return this.read(file).toString('utf8');
+    }
+    snapshot() {
+        return { ...this.#metrics };
+    }
+}
+export class MissingOptionalEventEmitter {
+    #emitted = new Set();
+    emit(input) {
+        const key = `${input.runId}\0${input.optional}`;
+        if (this.#emitted.has(key))
+            return null;
+        const event = {
+            schemaVersion: OPTIONAL_FALLBACK_SCHEMA_VERSION,
+            event: OPTIONAL_FALLBACK_EVENT,
+            package: FLOWGRID_TEST_PACKAGE,
+            ...input,
+            metrics: { ...input.metrics },
+        };
+        const result = validateMissingOptionalEvent(event);
+        if (!result.ok)
+            throw new Error(`Invalid missing-optional event: ${result.errors.join('; ')}`);
+        this.#emitted.add(key);
+        return event;
+    }
+}
+//# sourceMappingURL=fallback-evidence.js.map

package/dist/test/optional/fallback-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-evidence.js","sourceRoot":"","sources":["../../../src/test/optional/fallback-evidence.ts"],"names":[],"mappings":"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"}

package/engines/cases/README.md

@@ -0,0 +1,12 @@
+# Case plan checks
+
+`check-plans.mjs` parses every `cases/TC-*.yaml` under the project cwd and
+validates with Ajv draft 2020-12 against the package SSOT
+`schemas/testcase.schema.json` (resolved from this package, not the destination
+cwd). Override only for tests via `FLOWGRID_TESTCASE_SCHEMA`.
+
+Change testcase validation rules in that schema rather than in the checker.
+
+**schemaVersion: 2** — requires `testMatrix` (facet enum) and `steps` (min 1). Align with `flowgrid audit testcase` on the same file. Golden template: `harness/tests/templates/TC.example.yaml`.
+
+**Release gate:** `flowgrid cases:gate [--strict] [--docs-root …] [--json] [--no-coverage]` — schema + TC audit + bundle `traceability` + per-screen matrix facets + `cases:coverage`. Use `--strict` before IT/release.

package/engines/cases/check-coverage.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Compare SC coverage_plan ↔ TC coverage (same scenario).
+ * Usage: pnpm check:coverage
+ */
+import { readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parse } from 'yaml'
+
+const root = process.cwd()
+
+async function main() {
+  const scenarios = await listFiles(path.join(root, 'scenarios'), /^SC-.*\.md$/i)
+  const cases = await listFiles(path.join(root, 'cases'), /^TC-.*\.ya?ml$/i)
+  const byScenario = new Map()
+
+  for (const file of cases) {
+    const tc = parse(await readFile(file, 'utf8')) ?? {}
+    const sc = tc.refs?.scenario
+    if (!sc) continue
+    if (!byScenario.has(sc)) byScenario.set(sc, [])
+    byScenario.get(sc).push({
+      id: tc.id,
+      coverage: new Set(tc.coverage ?? []),
+      file: path.relative(root, file),
+    })
+  }
+
+  const gaps = []
+  const notes = []
+
+  for (const file of scenarios) {
+    const raw = await readFile(file, 'utf8')
+    const fm = parseFrontmatter(raw)
+    const scId = fm.id || path.basename(file, '.md')
+    const plan = Array.isArray(fm.coverage_plan) ? fm.coverage_plan : []
+    if (!plan.length) {
+      notes.push(`${path.relative(root, file)}: no coverage_plan in frontmatter`)
+      continue
+    }
+    const tcs = byScenario.get(scId) || []
+    const covered = new Set()
+    for (const tc of tcs) for (const c of tc.coverage) covered.add(c)
+
+    for (const facet of plan) {
+      if (!covered.has(facet)) {
+        gaps.push(`${scId}: coverage_plan "${facet}" — chưa có TC (files: ${tcs.map((t) => t.id).join(', ') || 'none'})`)
+      }
+    }
+    for (const tc of tcs) {
+      for (const c of tc.coverage) {
+        if (!plan.includes(c)) {
+          notes.push(`${tc.id}: coverage "${c}" không nằm trong ${scId} coverage_plan`)
+        }
+      }
+    }
+  }
+
+  for (const n of notes) console.warn(`  note: ${n}`)
+  if (gaps.length) {
+    console.error('check:coverage FAILED — thiếu bao phủ:')
+    for (const g of gaps) console.error(`  - ${g}`)
+    process.exit(1)
+  }
+  console.log(`check:coverage OK (${scenarios.length} SC, ${cases.length} TC)`)
+}
+
+function parseFrontmatter(raw) {
+  if (!raw.startsWith('---')) return {}
+  const end = raw.indexOf('\n---', 3)
+  if (end < 0) return {}
+  try {
+    return parse(raw.slice(3, end)) ?? {}
+  } catch {
+    return {}
+  }
+}
+
+async function listFiles(dir, re) {
+  const out = []
+  for (const entry of await listEntries(dir)) {
+    const p = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      out.push(...(await listFiles(p, re)))
+      continue
+    }
+    if (entry.isFile() && re.test(entry.name)) out.push(p)
+  }
+  return out.sort()
+}
+
+async function listEntries(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/engines/cases/check-plans.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Validate TC-*.yaml against schemas/testcase.schema.json (package SSOT).
+ * Usage: pnpm check:plans  |  flowgrid cases:check
+ */
+import path from 'node:path'
+import { listCaseYamlUnderProject } from './lib/list-case-yaml.mjs'
+import { validateTcFile } from './lib/validate-tc-schema.mjs'
+
+const root = process.cwd()
+
+async function main() {
+  const files = await listCaseYamlUnderProject(root)
+  const errors = []
+  for (const file of files) {
+    const result = await validateTcFile(file, root)
+    if (!result.ok) errors.push(...result.errors)
+  }
+  if (errors.length) {
+    console.error('check:plans FAILED')
+    for (const e of errors) console.error(`  - ${e}`)
+    process.exit(1)
+  }
+  console.log(`check:plans OK (${files.length} case(s))`)
+}
+
+main().catch((e) => {
+  console.error('check:plans FAILED')
+  console.error(`  - ${e.message}`)
+  process.exit(1)
+})