@llman-sdd/core 0.1.4 → 0.2.0

package/src/validation/staleness.ts

@@ -0,0 +1,158 @@
+/**
+ * Staleness evaluator (validation/staleness parity): v1 `sdd/spec/staleness.rs`
+ * observable contract — status/baseRef/scope/touchedPaths/specUpdated/dirty/
+ * notes plus per-capability staleness issues. Pure: git + env are injected.
+ */
+
+import type { GitLike } from '../git/spawnGit.ts';
+
+export type StalenessStatus = 'OK' | 'INFO' | 'WARN' | 'STALE' | 'NOTAPPLICABLE';
+
+export interface StalenessInfo {
+  status: StalenessStatus;
+  baseRef: string | null;
+  scope: string[];
+  touchedPaths: string[];
+  specUpdated: boolean;
+  dirty: boolean;
+  notes: string[];
+}
+
+export interface StalenessIssue {
+  level: 'ERROR' | 'WARNING' | 'INFO';
+  path: string;
+  message: string;
+}
+
+export interface StalenessDeps {
+  git: GitLike;
+  root: string;
+  /** spec file path relative to root, e.g. `llmanspec/specs/auth.feature` */
+  specRel: string;
+  /** scope entries from the `# scope:` header (raw, unnormalized) */
+  scope: string[];
+  /** env override for LLMANSPEC_BASE_REF */
+  baseRefEnv?: string;
+  defaultBranchName?: string;
+}
+
+const normalizePath = (value: string): string =>
+  value.trim().replace(/^\.\//u, '').replace(/^\/+/u, '').replace(/\/+$/u, '');
+
+const scopeMatches = (path: string, scope: readonly string[]): boolean => {
+  const p = normalizePath(path);
+  return scope.some((s) => p === s || p.startsWith(`${s}/`));
+};
+
+export function notApplicableStaleness(): StalenessInfo {
+  return {
+    status: 'NOTAPPLICABLE',
+    baseRef: null,
+    scope: [],
+    touchedPaths: [],
+    specUpdated: false,
+    dirty: false,
+    notes: [],
+  };
+}
+
+const DIRTY_MSG = 'Working tree is dirty; results may be unreliable.';
+const SCOPE_MISSING_MSG = 'Note: Spec validation scope is missing.';
+const BASE_MISSING_MSG =
+  "Note: Unable to resolve base ref for staleness check. Set LLMANSPEC_BASE_REF (e.g. 'main' or 'origin/main'), or upgrade llman if below 0.0.60.";
+
+/**
+ * Evaluate staleness for one capability spec — v1 status semantics.
+ * Returns the info object plus warning/info issues (strict escalation is the
+ * caller's job, matching v1 `apply_strict`).
+ */
+export function evaluateStaleness(deps: StalenessDeps): {
+  info: StalenessInfo;
+  issues: StalenessIssue[];
+} {
+  const { git, specRel, scope, baseRefEnv } = deps;
+  const issues: StalenessIssue[] = [];
+  const notes: string[] = [];
+  const normScope = scope.map(normalizePath).filter((s) => s !== '');
+
+  const rawBaseRef =
+    baseRefEnv !== undefined && baseRefEnv.trim() !== '' ? baseRefEnv.trim() : null;
+  let baseRef: string | null = null;
+  let mergeBase: string | null = null;
+
+  if (rawBaseRef !== null) {
+    baseRef = rawBaseRef;
+    mergeBase = revParse(git, rawBaseRef);
+  } else {
+    const defaultBranchName = deps.defaultBranchName ?? defaultBranchNameFn(git);
+    mergeBase = git.runOpt(['merge-base', defaultBranchName, 'HEAD']);
+    if (mergeBase !== null) baseRef = mergeBase;
+  }
+
+  let status: StalenessStatus = 'OK';
+  if (normScope.length === 0) {
+    status = 'WARN';
+    notes.push(SCOPE_MISSING_MSG);
+    issues.push({ level: 'WARNING', path: `${specId()}/staleness`, message: SCOPE_MISSING_MSG });
+  }
+  if (mergeBase === null && rawBaseRef === null) {
+    status = 'WARN';
+    notes.push(BASE_MISSING_MSG);
+    issues.push({ level: 'WARNING', path: `${specId()}/staleness`, message: BASE_MISSING_MSG });
+  }
+
+  let touchedPaths: string[] = [];
+  let specUpdated = false;
+  if (status !== 'WARN' && baseRef !== null && mergeBase !== null) {
+    const diff = git.runOpt(['diff', '--name-only', `${baseRef}...HEAD`]) ?? '';
+    const paths =
+      diff === ''
+        ? []
+        : diff
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l !== '');
+    if (paths.length > 0) {
+      specUpdated = paths.some((p) => normalizePath(p) === normalizePath(specRel));
+      touchedPaths = paths.filter((p) => scopeMatches(p, normScope));
+    }
+    if (touchedPaths.length > 0 && !specUpdated) {
+      status = 'STALE' as StalenessStatus;
+      issues.push({ level: 'WARNING', path: `${specId()}/staleness`, message: STALE_MSG });
+    } else if (specUpdated && touchedPaths.length === 0) {
+      status = 'INFO';
+      notes.push(SPEC_UPDATED_MSG);
+    }
+  }
+
+  // Tolerant: outside a git repo (or on git failure) treat as dirty (v1 unwrap_or(true)).
+  const dirty = (git.runOpt(['status', '--porcelain']) ?? 'dirty') !== '';
+  if (dirty) {
+    if (status === 'OK' || status === 'STALE') status = 'INFO';
+    notes.push(DIRTY_MSG);
+    issues.push({ level: 'INFO', path: `${specId()}/staleness`, message: DIRTY_MSG });
+  }
+
+  return {
+    info: { status, baseRef, scope: normScope, touchedPaths, specUpdated, dirty, notes },
+    issues,
+  };
+
+  function specId(): string {
+    return deps.specRel.replace(/^llmanspec\/specs\//u, '').replace(/\.feature$/u, '');
+  }
+}
+
+const STALE_MSG = 'Note: Spec files changed on the base branch; re-review the spec.';
+const SPEC_UPDATED_MSG = 'Note: Spec updated on this branch.';
+
+function revParse(git: GitLike, ref: string): string | null {
+  return git.runOpt(['rev-parse', '--verify', '--quiet', ref]) ?? null;
+}
+
+function defaultBranchNameFn(git: GitLike): string {
+  if (git.runOpt(['show-ref', '--verify', '--quiet', 'refs/heads/main']) !== null) return 'main';
+  if (git.runOpt(['show-ref', '--verify', '--quiet', 'refs/heads/master']) !== null)
+    return 'master';
+  return 'main';
+}

package/src/validation/validate.ts

@@ -1,7 +1,8 @@
 /**
  * Validation engine (validation capability): aggregates Phase-2 parse errors
- * plus the verdict-equivalent gates probed from v1 (r11/r12). Pure —
- * filesystem access is injected via SpecIo.
+ * plus the verdict-equivalent gates (r11/r12, ordered to match v1
+ * `spec/validation.rs` observable issue order). Pure — filesystem access is
+ * injected via SpecIo.
  */
 import type { CapabilityDoc } from '../spec/ir.ts';
 import { MUST_WORD_RE } from '../spec/ir.ts';
@@ -11,7 +12,7 @@ export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
 
 export interface ValidationItem {
   level: ValidationLevel;
-  /** Gate anchor, e.g. `t/rule/ok` or `t/valid_scope` (v1-style). */
+  /** Gate anchor, e.g. `t/rule/ok` or `t/valid_scope` (v1-style `path`). */
   id: string;
   message: string;
 }
@@ -39,79 +40,148 @@ export interface ValidationReport {
   failed: boolean;
 }
 
+const rulesPath = (cap: string): string => `${cap}/rules`;
+const acceptanceReqPath = (cap: string, name: string): string => `${cap}/acceptance/${name}/@req`;
+const coveragePath = (cap: string): string => `${cap}/coverage`;
+
 export function validateCapability(
   entry: SpecEntry,
   duplicatesFor: (reqId: string) => boolean,
   io: SpecIo,
+  opts: { strict?: boolean } = {},
 ): SpecVerdict {
   const { doc } = entry;
   const cap = doc.header.capability ?? entry.fileName;
+  const strict = opts.strict === true;
   const items: ValidationItem[] = [];
 
-  // Header gates (r12): capability header is an ERROR (v1 parity); missing
-  // purpose/scope degrade to WARNING.
+  const push = (level: ValidationLevel, id: string, message: string): void => {
+    items.push({ level, id, message });
+  };
+
+  // Header gates (r12 / v1 spec_meta). v1 treats a missing `# capability:`
+  // header as a parse-level failure: only `file` + registry-scan issues are
+  // emitted and all single-track gates are skipped.
   if (doc.header.capability === null) {
-    items.push({
-      level: 'ERROR',
-      id: 'file',
-      message: 'missing `# capability:` header comment',
-    });
+    const msg = `spec \`${cap}\`: missing \`# capability:\` header comment (spec-format r133)`;
+    push('ERROR', 'file', msg);
+    push('ERROR', 'llmanspec/specs', `Failed to scan req_id index: ${msg}`);
+    return { fileName: entry.fileName, capability: cap, ok: false, items };
   }
-  if (doc.header.purpose === null) {
-    items.push({ level: 'WARNING', id: 'file', message: 'missing `# purpose:` header comment' });
+  if (doc.header.purpose === null || doc.header.purpose.trim() === '') {
+    push(
+      'ERROR',
+      `${cap}/purpose`,
+      '`# purpose:` header comment must not be empty (spec-format r133)',
+    );
   }
   if (doc.header.scope === null) {
-    items.push({ level: 'WARNING', id: 'file', message: 'missing `# scope:` header comment' });
+    push(
+      'ERROR',
+      `${cap}/valid_scope`,
+      'Spec valid_scope must not be empty (add it inside the .toon document).',
+    );
   } else {
-    for (const p of doc.header.scope
+    // r42: missing valid_scope paths are independent failures —
+    // ERROR (nonzero exit) under --strict, WARNING otherwise.
+    const missing = doc.header.scope
       .split(',')
       .map((s) => s.trim())
-      .filter((s) => s !== '')) {
-      if (!io.exists(p)) {
-        items.push({
-          level: 'ERROR',
-          id: `${cap}/valid_scope`,
-          message: `valid_scope path(s) do not exist on disk: ${p}`,
-        });
-      }
+      .filter((s) => s !== '')
+      .filter((s) => !io.exists(s));
+    if (missing.length > 0) {
+      push(
+        strict ? 'ERROR' : 'WARNING',
+        `${cap}/valid_scope`,
+        `valid_scope path(s) do not exist on disk: ${missing.join(', ')}`,
+      );
     }
   }
 
-  // Structural errors from parsing (mutual exclusion, manual orphan, nested
-  // rule scenarios) — all ERROR level (v1 verdict parity). Header gates and
-  // the MUST-word gate are owned by this layer (mapped below), so the
-  // parser's duplicate findings are skipped here.
+  // Spec name must match the capability id (flat stem).
+  if (doc.header.capability !== null && doc.header.capability.trim() !== cap) {
+    push(
+      'WARNING',
+      `${cap}/meta.name`,
+      `Spec \`# capability:\` header must match spec id (flat file stem or directory name): \`${doc.header.capability.trim()}\` != \`${cap}\``,
+    );
+  }
+
+  // Feature title must be non-empty.
+  if ((doc.featureName ?? '').trim() === '') {
+    push('ERROR', `${cap}/feature`, 'Feature line must carry a title');
+  }
+
+  // Parser-level structural errors (mutual exclusion, manual orphan, nested
+  // rule scenarios). Header gates and the MUST-word gate are owned here
+  // (mapped below), so the parser's duplicate findings are skipped.
   const OWNED_BY_THIS_LAYER = ['missing-header:', 'rule:missing-must-word'];
   for (const err of doc.errors) {
     if (OWNED_BY_THIS_LAYER.some((prefix) => err.code.startsWith(prefix))) continue;
-    items.push({ level: 'ERROR', id: `${cap}/${err.code}`, message: err.message });
+    push('ERROR', err.code.startsWith('file') ? 'file' : `${cap}/${err.code}`, err.message);
+  }
+
+  // Single-track gates (v1 validate_single_track order).
+  const human = doc.scenarios.filter((s) => s.classification === 'human');
+  const acceptance = doc.scenarios.filter((s) => s.classification === 'executable');
+
+  if (human.length === 0) {
+    push('ERROR', rulesPath(cap), 'spec must define at least one @human constraint scenario');
   }
 
   for (const scenario of doc.scenarios) {
     const anchor = `${cap}/rule/${scenario.name}`;
     if (scenario.classification === 'human') {
       if (scenario.reqIds.length === 0) {
-        items.push({
-          level: 'ERROR',
-          id: anchor,
-          message: '@human constraint scenario must carry an @req:<req_id> tag',
-        });
+        push('ERROR', anchor, '@human constraint scenario must carry an @req:<req_id> tag');
       }
       if (!MUST_WORD_RE.test(scenario.statement)) {
-        items.push({
-          level: 'ERROR',
-          id: anchor,
-          message: 'constraint statement must contain MUST/SHALL (or 必须/不得/禁止)',
-        });
+        push('ERROR', anchor, 'constraint statement must contain MUST/SHALL (or 必须/不得/禁止)');
       }
+    } else if (scenario.classification === 'executable') {
+      // (pairing handled below, after all rule req ids are known)
+    } else {
+      push(
+        'WARNING',
+        `${cap}/scenario/${scenario.name}`,
+        `scenario \`${scenario.name}\` carries neither @human nor @executable; tag it or drop it`,
+      );
     }
     for (const reqId of scenario.reqIds) {
       if (duplicatesFor(reqId)) {
-        items.push({
-          level: 'ERROR',
-          id: `${cap}/registry/${reqId}`,
-          message: `global duplicate req_id \`${reqId}\` used by multiple capabilities`,
-        });
+        push(
+          'ERROR',
+          `${cap}/registry/${reqId}`,
+          `global duplicate req_id \`${reqId}\` used by multiple capabilities`,
+        );
+      }
+    }
+  }
+
+  // Dangling acceptance @req links (v1 order: acceptance/@req then coverage).
+  const ruleReqIds = new Set(human.flatMap((s) => s.reqIds));
+  for (const sc of acceptance) {
+    for (const rid of sc.reqIds) {
+      if (!ruleReqIds.has(rid)) {
+        push(
+          'ERROR',
+          acceptanceReqPath(cap, sc.name),
+          `@req:${rid} on acceptance scenario \`${sc.name}\` has no matching @human constraint`,
+        );
+      }
+    }
+  }
+
+  // Rule coverage INFO (r134 pending rules).
+  for (const sc of human) {
+    for (const rid of sc.reqIds) {
+      const covered = acceptance.some((a) => a.reqIds.includes(rid));
+      if (!covered) {
+        push(
+          'INFO',
+          coveragePath(cap),
+          `rule ${rid} is pending: no @executable acceptance scenario and no @manual waiver`,
+        );
       }
     }
   }
@@ -149,3 +219,8 @@ export function validateAllSpecs(entries: readonly SpecEntry[], io: SpecIo): Val
 
   return { verdicts, lines, failed };
 }
+
+/** v1 `apply_strict`: WARNING issues escalate to ERROR when --strict. */
+export function applyStrict<T extends { level: ValidationLevel }>(items: readonly T[]): T[] {
+  return items.map((i) => (i.level === 'WARNING' ? { ...i, level: 'ERROR' as const } : i));
+}