@sigloch/contracts 0.7.0

package/dist/se/quality-rules.js

@@ -0,0 +1,206 @@
+// ---------------------------------------------------------------------------
+// Weasel words list (BQ-01)
+// ---------------------------------------------------------------------------
+const WEASEL_WORDS = [
+    'should', 'may', 'might', 'appropriate', 'etc', 'adequate', 'as needed',
+    'various', 'some', 'often', 'usually', 'normally', 'generally', 'typically',
+    'mostly', 'largely', 'commonly', 'presumably', 'possibly', 'potentially',
+    'approximately', 'roughly', 'around', 'about', 'near', 'nearly',
+    // CR-121 P1: Extended from graphengine requirements-engineer.md
+    'fast', 'slow', 'easy', 'simple', 'flexible', 'scalable', 'robust',
+    'sufficient', 'reasonable', 'minimal', 'optimal', 'best effort',
+    'when possible', 'as far as practicable',
+];
+const weaselPattern = new RegExp(`\\b(${WEASEL_WORDS.map(w => w.replace(/\s+/g, '\\s+')).join('|')})\\b`, 'i');
+// ---------------------------------------------------------------------------
+// Measurable criterion regex (BQ-02)
+// ---------------------------------------------------------------------------
+const measurablePattern = /(\d+[\s]*(ms|s|sec|min|%|percent|byte|MB|GB|times|x|sessions?)|\b(must|shall|exactly|at least|at most|no more than|within|before|after|greater|less|equal|minimum|maximum|genau|mindestens|hoechstens|höchstens|nicht mehr als|innerhalb|groesser|größer|kleiner|gleich)\b)/i;
+// ---------------------------------------------------------------------------
+// Helper: filter REQ elements
+// ---------------------------------------------------------------------------
+function reqElements(graph) {
+    return graph.elements.filter(e => e.type === 'REQ');
+}
+// ---------------------------------------------------------------------------
+// BQ-01 Unambiguous — detect weasel words in REQ descriptions
+// ---------------------------------------------------------------------------
+export function bq01Unambiguous(graph) {
+    return reqElements(graph)
+        .filter(req => weaselPattern.test(req.description))
+        .map(req => {
+        const match = req.description.match(weaselPattern);
+        return {
+            rule_id: 'BQ-01',
+            severity: 'warning',
+            element_id: req.id,
+            message: `${req.id} contains weasel word "${match?.[1]}"`,
+            fix_hint: 'Replace vague language with precise, testable statements',
+            context: {
+                element_type: req.type,
+                element_name: req.name,
+                current_description: req.description,
+            },
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// BQ-02 Verifiable — REQ must contain at least one measurable criterion
+// ---------------------------------------------------------------------------
+export function bq02Verifiable(graph) {
+    return reqElements(graph)
+        .filter(req => !measurablePattern.test(req.description))
+        .map(req => ({
+        rule_id: 'BQ-02',
+        severity: 'warning',
+        element_id: req.id,
+        message: `${req.id} has no measurable criterion`,
+        fix_hint: 'Add a concrete metric, threshold, or comparison operator',
+        context: {
+            element_type: req.type,
+            element_name: req.name,
+            current_description: req.description,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// BQ-04 Necessary — semantic duplicate REQ detection (CR-054)
+// ---------------------------------------------------------------------------
+/** Threshold above which two REQs are considered near-duplicates. */
+const BQ04_SIMILARITY_THRESHOLD = 0.85;
+/**
+ * Module-level similarity matrix + REQ ID list, set by `setBQ04SimilarityMatrix()`.
+ * When null, bq04Necessary returns [] (backward-compat).
+ */
+let _bq04Matrix = null;
+/**
+ * Inject a pre-computed similarity matrix for BQ-04.
+ * Call this before evaluateBQRules() when embeddings are available.
+ * Pass null to clear.
+ */
+export function setBQ04SimilarityMatrix(data) {
+    _bq04Matrix = data;
+}
+/**
+ * BQ-04 checks for duplicate / near-duplicate requirements using
+ * pre-computed embedding similarity. Returns [] when no matrix is set.
+ */
+export function bq04Necessary(graph) {
+    if (!_bq04Matrix)
+        return [];
+    const { reqIds, matrix } = _bq04Matrix;
+    const violations = [];
+    const seen = new Set();
+    for (let i = 0; i < reqIds.length; i++) {
+        for (let j = i + 1; j < reqIds.length; j++) {
+            const sim = matrix[i][j];
+            if (sim < BQ04_SIMILARITY_THRESHOLD)
+                continue;
+            const pairKey = `${reqIds[i]}:${reqIds[j]}`;
+            if (seen.has(pairKey))
+                continue;
+            seen.add(pairKey);
+            const pct = Math.round(sim * 100);
+            // Determine UC ownership via compose traces for overlap hint
+            const ucA = findOwnerUC(graph, reqIds[i]);
+            const ucB = findOwnerUC(graph, reqIds[j]);
+            const overlapHint = ucA && ucB && ucA !== ucB
+                ? ` — UC overlap: ${ucA} and ${ucB} have overlapping concerns`
+                : '';
+            const elJ = graph.elements.find(e => e.id === reqIds[j]);
+            const elI = graph.elements.find(e => e.id === reqIds[i]);
+            violations.push({
+                rule_id: 'BQ-04',
+                severity: 'warning',
+                element_id: reqIds[j],
+                message: `${reqIds[j]} is ${pct}% similar to ${reqIds[i]}${overlapHint}`,
+                fix_hint: 'Merge into single REQ or differentiate descriptions',
+                context: {
+                    element_type: elJ?.type,
+                    element_name: elJ?.name,
+                    candidate_targets: elI ? [{ id: elI.id, type: elI.type, name: elI.name }] : undefined,
+                    current_description: elJ?.description,
+                },
+            });
+        }
+    }
+    return violations;
+}
+/** Find the UC that composes a given REQ (via UC [compose] → REQ trace). */
+function findOwnerUC(graph, reqId) {
+    const trace = graph.traces.find(t => t.target === reqId && t.type === 'compose'
+        && graph.elements.some(e => e.id === t.source && e.type === 'UC'));
+    return trace?.source ?? null;
+}
+// ---------------------------------------------------------------------------
+// BQ-06 Conforming — REQ description should follow "system shall" pattern
+// ---------------------------------------------------------------------------
+const conformingPattern = /\b(shall|must|must not)\s+\w+/i;
+const conformingPatternDE = /\b(soll|muss|darf nicht)\s+\w+/i;
+export function bq06Conforming(graph) {
+    return reqElements(graph)
+        .filter(req => {
+        const desc = req.description.trim();
+        return !conformingPattern.test(desc) && !conformingPatternDE.test(desc);
+    })
+        .map(req => ({
+        rule_id: 'BQ-06',
+        severity: 'warning',
+        element_id: req.id,
+        message: `${req.id} does not follow "System shall..." pattern`,
+        fix_hint: 'Start description with "The system shall <verb>" or "Das System soll/muss <verb>"',
+        context: {
+            element_type: req.type,
+            element_name: req.name,
+            current_description: req.description,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// BQ-07 Complete — REQ must have meaningful description and no placeholders
+// ---------------------------------------------------------------------------
+const placeholderPattern = /\b(TBD|TBR|TODO|placeholder|to be determined)\b|needs\s.*review/i;
+const BQ07_MIN_DESC_LENGTH = 20;
+export function bq07Complete(graph) {
+    return reqElements(graph)
+        .filter(req => {
+        const tooShort = req.description.trim().length < BQ07_MIN_DESC_LENGTH;
+        const hasPlaceholder = placeholderPattern.test(req.description);
+        return tooShort || hasPlaceholder;
+    })
+        .map(req => {
+        const reasons = [];
+        if (req.description.trim().length < BQ07_MIN_DESC_LENGTH) {
+            reasons.push(`description too short (${req.description.trim().length}/${BQ07_MIN_DESC_LENGTH} chars)`);
+        }
+        if (placeholderPattern.test(req.description)) {
+            reasons.push('contains placeholder');
+        }
+        return {
+            rule_id: 'BQ-07',
+            severity: 'warning',
+            element_id: req.id,
+            message: `${req.id} is incomplete: ${reasons.join(', ')}`,
+            fix_hint: 'Write a meaningful description (min 20 chars) and resolve all TBD/TBR/TODO placeholders',
+            context: {
+                element_type: req.type,
+                element_name: req.name,
+                current_description: req.description,
+            },
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Aggregated array & convenience runner
+// ---------------------------------------------------------------------------
+export const BQ_RULES = [
+    { id: 'BQ-01', name: 'Unambiguous', severity: 'warning', evaluate: bq01Unambiguous },
+    { id: 'BQ-02', name: 'Verifiable', severity: 'warning', evaluate: bq02Verifiable },
+    { id: 'BQ-04', name: 'Necessary', severity: 'warning', evaluate: bq04Necessary },
+    { id: 'BQ-06', name: 'Conforming', severity: 'warning', evaluate: bq06Conforming },
+    { id: 'BQ-07', name: 'Complete', severity: 'warning', evaluate: bq07Complete },
+];
+/** Run all BQ rules against a graph, returning combined violations. */
+export function evaluateBQRules(graph) {
+    return BQ_RULES.flatMap(rule => rule.evaluate(graph));
+}

package/dist/se/readiness.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CR-120: Readiness dimension schemas for dynamic phase readiness.
+ * Dimensions emerge from graph state — no state machine.
+ */
+import { z } from 'zod/v4';
+export declare const ReadinessDimension: z.ZodEnum<{
+    req: "req";
+    uc: "uc";
+    arch: "arch";
+    alloc: "alloc";
+    ver: "ver";
+    schema: "schema";
+    cr: "cr";
+    ms: "ms";
+}>;
+export type ReadinessDimensionType = z.infer<typeof ReadinessDimension>;
+export declare const ReadinessScore: z.ZodObject<{
+    dimension: z.ZodEnum<{
+        req: "req";
+        uc: "uc";
+        arch: "arch";
+        alloc: "alloc";
+        ver: "ver";
+        schema: "schema";
+        cr: "cr";
+        ms: "ms";
+    }>;
+    score: z.ZodNumber;
+    violations: z.ZodNumber;
+    applicable: z.ZodNumber;
+    ready: z.ZodBoolean;
+}, z.core.$strip>;
+export type ReadinessScoreType = z.infer<typeof ReadinessScore>;
+export declare const ReadinessReport: z.ZodObject<{
+    scores: z.ZodArray<z.ZodObject<{
+        dimension: z.ZodEnum<{
+            req: "req";
+            uc: "uc";
+            arch: "arch";
+            alloc: "alloc";
+            ver: "ver";
+            schema: "schema";
+            cr: "cr";
+            ms: "ms";
+        }>;
+        score: z.ZodNumber;
+        violations: z.ZodNumber;
+        applicable: z.ZodNumber;
+        ready: z.ZodBoolean;
+    }, z.core.$strip>>;
+    emergentPhase: z.ZodString;
+    phaseScore: z.ZodNumber;
+    overallScore: z.ZodNumber;
+    timestamp: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ReadinessReportType = z.infer<typeof ReadinessReport>;
+/**
+ * Rule → dimension mapping. Some rules belong to multiple dimensions;
+ * here we assign primary dimension per rule. R-01 appears in 'ver' (primary)
+ * since its core concern is test verification coverage.
+ */
+export declare const RULE_TO_DIMENSION: Record<string, ReadinessDimensionType>;

package/dist/se/readiness.js

@@ -0,0 +1,79 @@
+/**
+ * CR-120: Readiness dimension schemas for dynamic phase readiness.
+ * Dimensions emerge from graph state — no state machine.
+ */
+import { z } from 'zod/v4';
+export const ReadinessDimension = z.enum([
+    'req', // Requirements quality (BQ-01..07, RD-01..03)
+    'uc', // UC completeness (UC-01..06, R-14, FC-01..03)
+    'arch', // Functional architecture (R-02, R-03, R-10, R-12)
+    'alloc', // Module allocation (R-04)
+    'ver', // Test coverage (R-01, R-05)
+    'schema', // Interface completeness (SC-01..03)
+    'cr', // CR traceability (CR-R01..R03)
+    'ms', // Milestone planning (MS-01..02)
+]);
+export const ReadinessScore = z.object({
+    dimension: ReadinessDimension,
+    score: z.number().min(0).max(1), // 1 - (violations / applicable)
+    violations: z.number().int(),
+    applicable: z.number().int(),
+    ready: z.boolean(), // score >= 0.7
+});
+export const ReadinessReport = z.object({
+    scores: z.array(ReadinessScore),
+    emergentPhase: z.string(),
+    phaseScore: z.number().min(0).max(1), // CR-146: % progress of current phase
+    overallScore: z.number().min(0).max(1),
+    timestamp: z.iso.datetime(),
+});
+/**
+ * Rule → dimension mapping. Some rules belong to multiple dimensions;
+ * here we assign primary dimension per rule. R-01 appears in 'ver' (primary)
+ * since its core concern is test verification coverage.
+ */
+export const RULE_TO_DIMENSION = {
+    // req
+    'BQ-01': 'req', 'BQ-02': 'req', 'BQ-04': 'req',
+    'BQ-06': 'req', 'BQ-07': 'req',
+    'RD-01': 'req', 'RD-02': 'req', 'RD-03': 'req',
+    // trace/realization/allocation completeness rules (CR-228 D: previously unmapped → advisory fall-through)
+    'R-18': 'arch', 'R-19': 'ver', 'R-20': 'arch', 'R-21': 'ver',
+    'R-22': 'alloc', 'R-23': 'alloc', 'R-26': 'schema',
+    // uc
+    'UC-01': 'uc', 'UC-02': 'uc', 'UC-03': 'uc', 'UC-04': 'uc',
+    'UC-05': 'uc', 'UC-06': 'uc',
+    'R-14': 'uc', 'R-15': 'uc', 'R-16': 'uc', 'R-17': 'uc',
+    'FC-01': 'uc', 'FC-02': 'uc', 'FC-03': 'uc',
+    // arch
+    'R-02': 'arch', 'R-03': 'arch', 'R-10': 'arch', 'R-12': 'arch',
+    // alloc
+    'R-04': 'alloc',
+    // ver
+    'R-01': 'ver', 'R-05': 'ver',
+    // schema
+    'SC-01': 'schema', 'SC-02': 'schema', 'SC-03': 'schema',
+    // structural rules without primary dimension → assigned by closest concern
+    'R-08': 'arch',
+    // near-duplicate detection
+    'ND-01': 'arch', 'ND-02': 'schema',
+    // architecture metrics
+    'MT-01': 'alloc', 'MT-02': 'alloc', 'MT-03': 'alloc',
+    // CR traceability
+    'CR-R01': 'cr', 'CR-R02': 'cr', 'CR-R03': 'cr', 'CR-R04': 'cr',
+    // architecture optimization
+    'AO-D01': 'arch', 'AO-D03': 'arch',
+    // allocation rules (CR-191)
+    'CR-01': 'arch', 'RT-01': 'arch', 'PH-01': 'arch', 'CA-01': 'arch',
+    // milestone planning
+    'MS-01': 'ms', 'MS-02': 'ms', 'MS-03': 'ms',
+    // FMEA / risk
+    'FM-01': 'req', 'FM-02': 'req', 'FM-03': 'ver',
+    // NFR budget
+    'NFR-01': 'arch',
+    // cross-module IO (CR-192)
+    'IO-01': 'arch',
+    // view rules (CR-184)
+    'VR-01': 'ver',
+    'CL-01': 'uc',
+};

package/dist/se/rules.d.ts

@@ -0,0 +1,159 @@
+/**
+ * SE Rules — declarative config table + evaluation (version: see RULES_VERSION in ./index.ts).
+ * R-07/R-09/R-13 removed (CR-180), RD-01..03 added.
+ * @sigloch/contracts/se — single source of truth for SE validation rules.
+ */
+import { z } from 'zod/v4';
+import type { OntologyGraph } from './ontology.js';
+export declare const RuleSeverity: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+    info: "info";
+}>;
+export type RuleSeverity = z.infer<typeof RuleSeverity>;
+/** Candidate target for resolving a violation (e.g. a REQ to satisfy, a TEST to link). */
+export declare const ViolationCandidate: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        SYS: "SYS";
+        UC: "UC";
+        ACTOR: "ACTOR";
+        FCHAIN: "FCHAIN";
+        FUNC: "FUNC";
+        FLOW: "FLOW";
+        REQ: "REQ";
+        TEST: "TEST";
+        MOD: "MOD";
+        SCHEMA: "SCHEMA";
+        SESSION: "SESSION";
+        CR: "CR";
+        MS: "MS";
+    }>;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type ViolationCandidate = z.infer<typeof ViolationCandidate>;
+/** Graph context attached to a violation — enables prompt generation without extra DB queries. */
+export declare const ViolationContext: z.ZodObject<{
+    element_type: z.ZodOptional<z.ZodEnum<{
+        SYS: "SYS";
+        UC: "UC";
+        ACTOR: "ACTOR";
+        FCHAIN: "FCHAIN";
+        FUNC: "FUNC";
+        FLOW: "FLOW";
+        REQ: "REQ";
+        TEST: "TEST";
+        MOD: "MOD";
+        SCHEMA: "SCHEMA";
+        SESSION: "SESSION";
+        CR: "CR";
+        MS: "MS";
+    }>>;
+    element_name: z.ZodOptional<z.ZodString>;
+    candidate_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            SYS: "SYS";
+            UC: "UC";
+            ACTOR: "ACTOR";
+            FCHAIN: "FCHAIN";
+            FUNC: "FUNC";
+            FLOW: "FLOW";
+            REQ: "REQ";
+            TEST: "TEST";
+            MOD: "MOD";
+            SCHEMA: "SCHEMA";
+            SESSION: "SESSION";
+            CR: "CR";
+            MS: "MS";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    existing_traces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        type: z.ZodEnum<{
+            compose: "compose";
+            io: "io";
+            satisfy: "satisfy";
+            verify: "verify";
+            allocate: "allocate";
+            relation: "relation";
+            produces: "produces";
+        }>;
+    }, z.core.$strip>>>;
+    parent_module: z.ZodOptional<z.ZodString>;
+    current_description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ViolationContext = z.infer<typeof ViolationContext>;
+export declare const RuleViolation: z.ZodObject<{
+    rule_id: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>;
+    element_id: z.ZodString;
+    message: z.ZodString;
+    fix_hint: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodObject<{
+        element_type: z.ZodOptional<z.ZodEnum<{
+            SYS: "SYS";
+            UC: "UC";
+            ACTOR: "ACTOR";
+            FCHAIN: "FCHAIN";
+            FUNC: "FUNC";
+            FLOW: "FLOW";
+            REQ: "REQ";
+            TEST: "TEST";
+            MOD: "MOD";
+            SCHEMA: "SCHEMA";
+            SESSION: "SESSION";
+            CR: "CR";
+            MS: "MS";
+        }>>;
+        element_name: z.ZodOptional<z.ZodString>;
+        candidate_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodEnum<{
+                SYS: "SYS";
+                UC: "UC";
+                ACTOR: "ACTOR";
+                FCHAIN: "FCHAIN";
+                FUNC: "FUNC";
+                FLOW: "FLOW";
+                REQ: "REQ";
+                TEST: "TEST";
+                MOD: "MOD";
+                SCHEMA: "SCHEMA";
+                SESSION: "SESSION";
+                CR: "CR";
+                MS: "MS";
+            }>;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        existing_traces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            target: z.ZodString;
+            type: z.ZodEnum<{
+                compose: "compose";
+                io: "io";
+                satisfy: "satisfy";
+                verify: "verify";
+                allocate: "allocate";
+                relation: "relation";
+                produces: "produces";
+            }>;
+        }, z.core.$strip>>>;
+        parent_module: z.ZodOptional<z.ZodString>;
+        current_description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RuleViolation = z.infer<typeof RuleViolation>;
+export interface RuleDefinition {
+    id: string;
+    name: string;
+    severity: 'error' | 'warning' | 'info';
+    evaluate: (graph: OntologyGraph) => RuleViolation[];
+}
+export declare const V3_RULES: RuleDefinition[];
+/** Run all rules against a graph */
+export declare function evaluateRules(graph: OntologyGraph): RuleViolation[];