agent-sdd 1.0.3

package/dist/features/ready/domain/MarkerParser.js

@@ -0,0 +1,108 @@
+/*
+ * Two-stage scanner for `@covers <partition>:<id> [key=value]*` markers
+ * (CST-007). Pure: takes a string + filename, returns Marker[] with 1-based
+ * line numbers. Language-agnostic: byte/string scan, no AST.
+ */
+import { ID_TAIL_RE_SRC, PARTITION_PREFIX_RE_SRC, } from "../../../shared/domain/PartitionGrammar.js";
+export const ALLOWED_MARKER_KEYS = new Set([
+    "compatibility_action",
+]);
+/*
+ * Tail stops at `@` so a second `@covers` on the same line is reachable. The
+ * `compatibility_action=…` whitelist tokens never contain `@`, so this is a
+ * safe boundary in practice. Partition + id grammar is shared with Config
+ * validation via `PartitionGrammar`.
+ */
+const MARKER_RE = new RegExp(`@covers\\s+(${PARTITION_PREFIX_RE_SRC}:${ID_TAIL_RE_SRC})([^@\\n\\r]*)`, "g");
+/*
+ * Loose recogniser for `@covers`-shaped tokens that end in a valid id tail
+ * (`<TYPE>-<num>`) but whose prefix violates the strict partition grammar
+ * (e.g. uppercase segment). Used to surface near-miss advisories (OQ-017).
+ */
+const NEAR_MISS_RE = new RegExp(`@covers\\s+([A-Za-z0-9_:-]+:[A-Z]+-\\d+)`, "g");
+const STRICT_TARGET_RE = new RegExp(`^${PARTITION_PREFIX_RE_SRC}:${ID_TAIL_RE_SRC}$`);
+/** `@covers`-shaped tokens that look like a marker attempt (valid id tail) but
+ *  fail the strict partition grammar. Strictly-valid markers are excluded. */
+export function parseNearMisses(text, file) {
+    const out = [];
+    const lineStarts = lineStartOffsets(text);
+    NEAR_MISS_RE.lastIndex = 0;
+    let match;
+    while ((match = NEAR_MISS_RE.exec(text)) !== null) {
+        const target = match[1];
+        if (STRICT_TARGET_RE.test(target)) {
+            continue;
+        }
+        out.push({
+            text: target,
+            file,
+            line: lineNumberOf(lineStarts, match.index),
+        });
+    }
+    return out;
+}
+export function parseMarkers(text, file) {
+    const out = [];
+    const lineStarts = lineStartOffsets(text);
+    /* Reset regex state in case a stale lastIndex leaks across calls. */
+    MARKER_RE.lastIndex = 0;
+    let match;
+    while ((match = MARKER_RE.exec(text)) !== null) {
+        const target = match[1];
+        const rawTail = match[2] ?? "";
+        /*
+         * CST-007: split at the LAST `:` — the id tail has no `:`, so everything
+         * before the rightmost `:` is the partition prefix.
+         */
+        const colon = target.lastIndexOf(":");
+        const partition = target.slice(0, colon);
+        const id = target.slice(colon + 1);
+        const tail = parseTail(rawTail);
+        const offset = match.index;
+        const line = lineNumberOf(lineStarts, offset);
+        out.push({ partition, id, tail, file, line });
+    }
+    return out;
+}
+function parseTail(rawTail) {
+    const tail = {};
+    for (const token of rawTail.split(/\s+/)) {
+        if (token.length === 0) {
+            continue;
+        }
+        const eq = token.indexOf("=");
+        if (eq < 1) {
+            continue;
+        }
+        const key = token.slice(0, eq);
+        const value = token.slice(eq + 1);
+        if (!ALLOWED_MARKER_KEYS.has(key)) {
+            continue;
+        }
+        tail[key] = value;
+    }
+    return tail;
+}
+function lineStartOffsets(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\n") {
+            starts.push(i + 1);
+        }
+    }
+    return starts;
+}
+function lineNumberOf(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (lineStarts[mid] <= offset) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return lo + 1;
+}

package/dist/features/ready/domain/PartitionResolver.d.ts

@@ -0,0 +1 @@
+export { matchesGlob, fileInGlobs } from "../../../shared/domain/GlobMatch.js";

package/dist/features/ready/domain/PartitionResolver.js

@@ -0,0 +1,5 @@
+/*
+ * Glob-matching primitives moved to the shared kernel (used by both ready and
+ * lint). Re-exported here for the ready feature's existing import sites.
+ */
+export { matchesGlob, fileInGlobs } from "../../../shared/domain/GlobMatch.js";

package/dist/features/ready/domain/ReadyInput.d.ts

@@ -0,0 +1,6 @@
+export interface ReadyInput {
+    partitionFilter?: string;
+    /** When set, ready additionally runs the P2.3 semver-cascade diff against
+     *  this git ref (e.g. "HEAD~5", a tag, or a commit SHA). Off by default. */
+    against?: string;
+}

package/dist/features/ready/domain/ReadyInput.js

@@ -0,0 +1 @@
+export {};

package/dist/features/ready/domain/ReadyViolation.d.ts

@@ -0,0 +1,38 @@
+import type { ReadyViolationKindId } from "../../../shared/domain/DiagnosticRegistry.js";
+export type ReadyViolationKind = ReadyViolationKindId;
+export type ReadyErrorKind = "spec_parse_failed" | "config_invalid" | "unreadable_test_paths" | "internal";
+export interface ReadyViolation {
+    kind: ReadyViolationKind;
+    id?: string;
+    partition?: string;
+    status?: string;
+    file?: string;
+    line?: number;
+    expected?: string;
+    actual?: string;
+    remediation?: string;
+    source?: string;
+}
+export interface ReadyError {
+    kind: ReadyErrorKind;
+    message: string;
+    file?: string;
+}
+/** Non-blocking advisory (OQ-011/OQ-017): surfaced in the ready envelope but
+ *  never affects exit code. */
+export interface ReadyAdvisory {
+    kind: "covers_near_miss";
+    file: string;
+    line: number;
+    text: string;
+    remediation: string;
+}
+export interface ReadyEnvelope {
+    ok: boolean;
+    error: ReadyError | null;
+    violations: ReadyViolation[];
+    advisories: ReadyAdvisory[];
+}
+export declare function emptyEnvelope(): ReadyEnvelope;
+export declare function envelopeFromError(error: ReadyError): ReadyEnvelope;
+export declare function envelopeFromViolations(violations: ReadyViolation[]): ReadyEnvelope;

package/dist/features/ready/domain/ReadyViolation.js

@@ -0,0 +1,19 @@
+/*
+ * Discriminated union for sdd ready output. Encoded by CTR-014; the union is
+ * derived from src/shared/domain/DiagnosticRegistry.READY_VIOLATION_KINDS so
+ * that CTR-016 / SUR-009 / INV-010 stays the single source of truth.
+ */
+export function emptyEnvelope() {
+    return { ok: true, error: null, violations: [], advisories: [] };
+}
+export function envelopeFromError(error) {
+    return { ok: false, error, violations: [], advisories: [] };
+}
+export function envelopeFromViolations(violations) {
+    return {
+        ok: violations.length === 0,
+        error: null,
+        violations,
+        advisories: [],
+    };
+}

package/dist/features/ready/domain/Rules.d.ts

@@ -0,0 +1,22 @@
+import type { Partition } from "../../../shared/domain/Config.js";
+import type { LintRecord } from "../../../shared/domain/SpecRecord.js";
+import type { Marker } from "./MarkerParser.js";
+import type { ReadyViolation } from "./ReadyViolation.js";
+export interface PartitionView {
+    partition: Partition;
+    records: LintRecord[];
+    recordsById: Map<string, LintRecord>;
+    creditedMarkersById: Map<string, Marker[]>;
+}
+export declare function ruleUnapproved(view: PartitionView): ReadyViolation[];
+export declare function ruleUncovered(view: PartitionView): ReadyViolation[];
+export declare function ruleRemovedNoCompatTest(view: PartitionView): ReadyViolation[];
+export declare function ruleRemovedCompatActionMismatch(view: PartitionView): ReadyViolation[];
+export declare function ruleSurfaceUnapprovedRef(view: PartitionView): ReadyViolation[];
+export interface ScannedMarker {
+    marker: Marker;
+    isPartitionConfigured: boolean;
+    hasMatchingRecord: boolean;
+}
+export declare function ruleOrphanCovers(scanned: readonly ScannedMarker[]): ReadyViolation[];
+export declare function ruleUnknownPartitionCovers(scanned: readonly ScannedMarker[]): ReadyViolation[];

package/dist/features/ready/domain/Rules.js

@@ -0,0 +1,243 @@
+import { fileInGlobs } from "./PartitionResolver.js";
+const NORMATIVE = new Set([
+    "Behavior",
+    "Invariant",
+    "Contract",
+    "Scenario",
+    "NFR",
+    "Constraint",
+    "Policy",
+    "Migration",
+    "Delta",
+    "GeneratedArtifact",
+    "ExternalDependency",
+    "LocalizationContract",
+    "Surface",
+]);
+/*
+ * Surface is normative but exempt from individual coverage requirements; its
+ * members carry the obligation. Matches lint's OBLIGATIONLESS_TEMPLATES.
+ */
+const COVERAGE_EXEMPT_TEMPLATES = new Set(["Surface"]);
+export function ruleUnapproved(view) {
+    const out = [];
+    for (const rec of view.records) {
+        if (!isNormative(rec)) {
+            continue;
+        }
+        const status = rec.lifecycleStatus;
+        if (status !== "draft" && status !== "proposed") {
+            continue;
+        }
+        if (fileInGlobs(rec.file, view.partition.sandboxPaths)) {
+            continue;
+        }
+        out.push({
+            kind: "unapproved",
+            id: rec.id,
+            partition: view.partition.name,
+            status,
+            file: rec.file,
+            line: rec.line,
+            remediation: "promote via `sdd approve` or move into sandbox_paths",
+        });
+    }
+    return out;
+}
+export function ruleUncovered(view) {
+    const out = [];
+    for (const rec of view.records) {
+        if (!isNormative(rec)) {
+            continue;
+        }
+        if (rec.template !== null && COVERAGE_EXEMPT_TEMPLATES.has(rec.template)) {
+            continue;
+        }
+        if (rec.lifecycleStatus !== "approved" &&
+            rec.lifecycleStatus !== "deprecated") {
+            continue;
+        }
+        if (isNotApplicableTestObligation(rec)) {
+            continue;
+        }
+        if ((view.creditedMarkersById.get(rec.id) ?? []).length > 0) {
+            continue;
+        }
+        out.push({
+            kind: "uncovered",
+            id: rec.id,
+            partition: view.partition.name,
+            status: rec.lifecycleStatus,
+            file: rec.file,
+            line: rec.line,
+            remediation: "add `@covers " +
+                rec.id +
+                "` next to a test for this ID, or set `Test obligation: not_applicable + reason`",
+        });
+    }
+    return out;
+}
+export function ruleRemovedNoCompatTest(view) {
+    const out = [];
+    for (const rec of view.records) {
+        if (!isNormative(rec)) {
+            continue;
+        }
+        if (rec.lifecycleStatus !== "removed") {
+            continue;
+        }
+        const markers = view.creditedMarkersById.get(rec.id) ?? [];
+        const haveCompat = markers.some((m) => typeof m.tail.compatibility_action === "string");
+        if (haveCompat) {
+            continue;
+        }
+        out.push({
+            kind: "removed_no_compat_test",
+            id: rec.id,
+            partition: view.partition.name,
+            status: rec.lifecycleStatus,
+            file: rec.file,
+            line: rec.line,
+            remediation: "add a test with `@covers " +
+                rec.id +
+                " compatibility_action=<action>`",
+        });
+    }
+    return out;
+}
+export function ruleRemovedCompatActionMismatch(view) {
+    const out = [];
+    for (const rec of view.records) {
+        if (!isNormative(rec)) {
+            continue;
+        }
+        if (rec.lifecycleStatus !== "removed") {
+            continue;
+        }
+        const expected = readCompatibilityAction(rec);
+        if (expected === null) {
+            continue;
+        }
+        const markers = view.creditedMarkersById.get(rec.id) ?? [];
+        for (const m of markers) {
+            const actual = m.tail.compatibility_action;
+            if (typeof actual !== "string") {
+                continue;
+            }
+            if (actual === expected) {
+                continue;
+            }
+            out.push({
+                kind: "removed_compat_action_mismatch",
+                id: rec.id,
+                partition: view.partition.name,
+                status: rec.lifecycleStatus,
+                file: m.file,
+                line: m.line,
+                expected,
+                actual,
+                remediation: "align marker's compatibility_action= with the spec's compatibility_action",
+            });
+        }
+    }
+    return out;
+}
+export function ruleSurfaceUnapprovedRef(view) {
+    const out = [];
+    for (const rec of view.records) {
+        if (rec.template !== "Surface") {
+            continue;
+        }
+        const status = rec.lifecycleStatus;
+        if (status !== "approved" &&
+            status !== "deprecated" &&
+            status !== "removed") {
+            continue;
+        }
+        const members = readMembers(rec);
+        for (const memberId of members) {
+            const member = view.recordsById.get(memberId);
+            if (member === undefined) {
+                continue;
+            }
+            const ms = member.lifecycleStatus;
+            if (ms === "approved" || ms === "deprecated" || ms === "removed") {
+                continue;
+            }
+            out.push({
+                kind: "surface_unapproved_ref",
+                id: rec.id,
+                partition: view.partition.name,
+                status,
+                file: rec.file,
+                line: rec.line,
+                remediation: `member ${memberId} is ${ms ?? "missing-status"}; approve it before approving Surface ${rec.id}`,
+            });
+        }
+    }
+    return out;
+}
+export function ruleOrphanCovers(scanned) {
+    const out = [];
+    for (const s of scanned) {
+        if (!s.isPartitionConfigured) {
+            continue;
+        } /* covered by ruleUnknownPartitionCovers */
+        if (s.hasMatchingRecord) {
+            continue;
+        }
+        out.push({
+            kind: "orphan_covers",
+            id: `${s.marker.partition}:${s.marker.id}`,
+            partition: s.marker.partition,
+            file: s.marker.file,
+            line: s.marker.line,
+            remediation: "marker references an ID not present in that partition's spec; remove the marker or add the ID",
+        });
+    }
+    return out;
+}
+export function ruleUnknownPartitionCovers(scanned) {
+    const out = [];
+    for (const s of scanned) {
+        if (s.isPartitionConfigured) {
+            continue;
+        }
+        out.push({
+            kind: "unknown_partition_covers",
+            id: `${s.marker.partition}:${s.marker.id}`,
+            partition: s.marker.partition,
+            file: s.marker.file,
+            line: s.marker.line,
+            remediation: "configure the partition in `.sdd/config.json#partitions` or fix the marker prefix",
+        });
+    }
+    return out;
+}
+function isNormative(rec) {
+    return rec.template !== null && NORMATIVE.has(rec.template);
+}
+function isNotApplicableTestObligation(rec) {
+    const v = rec.parsed.test_obligation;
+    if (typeof v === "string" && v.startsWith("not_applicable")) {
+        return true;
+    }
+    if (isObject(v) && v.not_applicable !== undefined) {
+        return true;
+    }
+    return false;
+}
+function readCompatibilityAction(rec) {
+    const ca = rec.parsed.compatibility_action;
+    return typeof ca === "string" ? ca : null;
+}
+function readMembers(rec) {
+    const m = rec.parsed.members;
+    if (!Array.isArray(m)) {
+        return [];
+    }
+    return m.filter((v) => typeof v === "string");
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/features/ready/domain/SpecDiff.d.ts

@@ -0,0 +1,33 @@
+import type { LintRecord } from "../../../shared/domain/SpecRecord.js";
+export type DiffClassification = "predicate_change" | "content_change" | "none";
+export interface ClassifiedDiff {
+    id: string;
+    template: string | null;
+    classification: DiffClassification;
+    changedFields: string[];
+}
+/** Per-ID diff: classify each ID present in `curr` against `prev`. IDs new to
+ *  `curr` are classified as "content_change" (additive). IDs removed in
+ *  `curr` are not returned (the consumer detects removal separately via
+ *  lifecycle.status flips, which lint already covers). */
+export declare function classifyDiff(prev: ReadonlyArray<LintRecord>, curr: ReadonlyArray<LintRecord>): ClassifiedDiff[];
+/** Required bump for a single Surface, computed by walking reachable IDs. */
+export type RequiredBump = "patch" | "minor" | "major";
+export interface SurfaceBumpAnalysis {
+    surfaceId: string;
+    declaredVersion: string | null;
+    prevDeclaredVersion: string | null;
+    required: RequiredBump;
+    drivenBy: ClassifiedDiff[];
+}
+export declare function requiredSurfaceBumps(prev: ReadonlyArray<LintRecord>, curr: ReadonlyArray<LintRecord>, diffs: ReadonlyArray<ClassifiedDiff>): SurfaceBumpAnalysis[];
+export interface GAStructuralDiff {
+    surfaceId: string;
+    generatedArtifactId: string;
+    classification: Exclude<DiffClassification, "none">;
+}
+export declare function generatedArtifactStructuralDiffs(prev: ReadonlyArray<LintRecord>, curr: ReadonlyArray<LintRecord>, diffs: ReadonlyArray<ClassifiedDiff>): GAStructuralDiff[];
+/** Compare two semver strings ("0.3.0" vs "0.4.0") and return the actual bump.
+ *  Returns null if either string is unparseable. */
+export declare function actualBump(prev: string | null, curr: string | null): RequiredBump | null;
+export declare function bumpAtLeast(actual: RequiredBump | null, required: RequiredBump): boolean;