@llman-sdd/core 0.1.3 → 0.2.0

package/src/report/show.ts

@@ -41,8 +41,16 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     ? countTasks(io.readText(`${dir}/tasks.md`))
     : { completed: 0, total: 0 };
 
-  const cleanTree = isCleanTree(git);
-  const onBoundBranch = binding !== null && currentBranch(git) === binding.branch;
+  // v1 parity: show works (gracefully degraded gates) outside a git repo.
+  let cleanTree = false;
+  let current = null;
+  try {
+    cleanTree = isCleanTree(git);
+    current = currentBranch(git);
+  } catch {
+    current = null;
+  }
+  const onBoundBranch = binding !== null && current === binding.branch;
 
   // specs landing: bound changes must have touched llmanspec/specs/ since base
   let specsLanded = false;
@@ -60,7 +68,17 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
   const specReport = validateAllSpecs(discoverSpecs(deps.specsDir, io), io);
   const validateOk = !specReport.failed && (total === 0 || tasksDone);
 
-  const stageComplete = stage === 'full';
+  const stageHint = !hasDesign
+    ? 'add design.md (current: draft → designed)'
+    : !hasTasks
+      ? 'add tasks.md (current: designed → planned)'
+      : stage === 'planned'
+        ? 'bind via `llman sdd change start <id>` (planned → full)'
+        : '';
+  const tasksHint =
+    total > 0 && completed < total
+      ? `${total - completed} unchecked tasks`
+      : 'complete or check off remaining tasks';
 
   const gateChecks = [
     {
@@ -71,29 +89,30 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     {
       name: 'on-bound-branch',
       pass: onBoundBranch,
-      hint: onBoundBranch ? '' : 'change is not attached; run `llman-sdd change start <id>`',
+      hint: onBoundBranch ? '' : 'change is not attached; run `llman sdd change start <id>`',
     },
     {
       name: 'stage-complete',
-      pass: stageComplete,
-      hint: stageComplete ? '' : `add ${!hasDesign ? 'design.md' : 'tasks.md'} (current: ${stage})`,
+      pass: hasDesign && hasTasks,
+      hint: hasDesign && hasTasks ? '' : (stageHint as string),
     },
     {
       name: 'specs-landed',
-      pass: specsLanded,
-      hint: specsLanded
-        ? ''
-        : 'edit live specs on the bound branch and commit (or needs_specs_change: false)',
+      pass: specsLanded || !needsSpecsChange,
+      hint:
+        specsLanded || !needsSpecsChange
+          ? ''
+          : 'edit live specs on the bound branch and commit (or needs_specs_change: false)',
     },
     {
       name: 'tasks-done',
-      pass: tasksDone,
-      hint: tasksDone ? '' : `${total - completed} unchecked tasks`,
+      pass: tasksDone && total > 0,
+      hint: tasksDone && total > 0 ? '' : tasksHint,
     },
     {
       name: 'validate',
       pass: validateOk,
-      hint: validateOk ? '' : 'fix issues reported by `llman-sdd validate <id> --strict`',
+      hint: validateOk ? '' : 'fix issues reported by `llman sdd validate <id> --strict`',
     },
   ];
 

package/src/report/specHelpers.ts

@@ -14,9 +14,12 @@ export interface SpecHelperIo {
   listDir(path: string): string[];
 }
 
-/** Scan all specs under `specsDir` for @req:rN TAGS (not step text) and return the next free id. */
+/**
+ * v1 parity (`req_registry.rs::next_req_id_from_index`): smallest free rN over
+ * the RULE (@human) req ids only; acceptance-only req tags do not occupy ids.
+ */
 export function nextReqId(io: SpecHelperIo, specsDir: string): string {
-  let max = 0;
+  const used = new Set<number>();
   const walk = (dir: string): void => {
     if (!io.exists(dir)) return;
     for (const name of io.listDir(dir)) {
@@ -24,8 +27,10 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
       if (name.endsWith('.feature')) {
         const doc = parseCapability(io.readText(full), full);
         for (const scenario of doc.scenarios) {
+          if (scenario.classification !== 'human') continue;
           for (const reqId of scenario.reqIds) {
-            max = Math.max(max, Math.trunc(Number(reqId.replace(/^r/u, ''))));
+            const n = Math.trunc(Number(reqId.replace(/^r/u, '')));
+            if (Number.isFinite(n)) used.add(n);
           }
         }
       } else if (io.isDirectory(full)) {
@@ -34,7 +39,9 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
     }
   };
   walk(specsDir);
-  return `r${max + 1}`;
+  let n = 1;
+  while (used.has(n)) n += 1;
+  return `r${n}`;
 }
 
 export function skeletonContent(capability: string, reqId: string, locale: string): string {
@@ -53,10 +60,11 @@ export function scaffoldSpec(
   specsDir: string,
   capability: string,
   locale: string,
+  opts: { force?: boolean } = {},
 ): string {
   const reqId = nextReqId(io, specsDir);
   const path = `${specsDir}/${capability}.feature`;
-  if (io.exists(path)) throw new Error(`spec already exists: ${path}`);
+  if (!opts.force && io.exists(path)) throw new Error(`spec already exists: ${path}`);
   io.mkdirp('src/');
   io.writeText(path, skeletonContent(capability, reqId, locale));
   return path;

package/src/review/review.ts

@@ -1,3 +1,5 @@
+import type { GitLike } from '../git/spawnGit.ts';
+import { evaluateStaleness, notApplicableStaleness } from '../validation/staleness.ts';
 /**
  * Review aggregation (review-freeze capability, r23): five-signal review over
  * spec IR + validate sweep. Port of v1 sdd/review.rs observable contract.
@@ -26,6 +28,12 @@ export interface ReviewInput {
   boundChangeCount: number;
   /** Active change summaries for the strict sweep (pending tasks → FAIL). */
   activeChanges?: readonly { name: string; completedTasks: number; totalTasks: number }[];
+  /** Restrict per-capability signals (pending/manual/unbound/stale) to this capability. */
+  capability?: string;
+  /** git + root for real staleness evaluation (v1 parity). */
+  git?: GitLike;
+  root?: string;
+  specsDir?: string;
 }
 
 export interface ReviewResult {
@@ -35,17 +43,8 @@ export interface ReviewResult {
   exitCode: number;
 }
 
-function executableBound(
-  scenarioTags: readonly string[],
-  bindings: readonly TagBinding[] | null,
-): boolean {
-  if (!bindings || bindings.length === 0) return false;
-  const has = (t: string): boolean => scenarioTags.includes(t);
-  return bindings.some((b) => (b.kind === 'tags' ? b.tags.every((t) => has(t)) : false));
-}
-
 export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
-  const { entries, bindings, boundChangeCount } = input;
+  const { entries, boundChangeCount } = input;
   const strictChangeFails = (input.activeChanges ?? []).filter(
     (c) => c.totalTasks > 0 && c.completedTasks < c.totalTasks,
   );
@@ -59,18 +58,38 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
 
   for (const entry of sorted) {
     const cap = entry.doc.header.capability ?? entry.fileName;
+    // r33: per-capability signals honor the --capability filter; locked and
+    // validate stay global regardless.
+    if (input.capability !== undefined && cap !== input.capability) continue;
     const rules = entry.doc.scenarios.filter((s) => s.classification === 'human');
     const acceptance = entry.doc.scenarios.filter((s) => s.classification === 'executable');
     const acceptanceReqIds = new Set(acceptance.flatMap((s) => s.reqIds));
     const pending = rules.filter((r) => !r.reqIds.some((id) => acceptanceReqIds.has(id)));
     const manual = rules.filter((r) => r.manual);
-    const unbound = acceptance.filter((s) => !executableBound(s.tags, bindings));
+    // v1 r5: unbound = orphan acceptance scenarios (no @req link).
+    const unbound = acceptance.filter((s) => s.reqIds.length === 0);
 
     push('pending', cap, pending.length);
     push('manual', cap, manual.length);
     push('unbound', cap, unbound.length);
-    // staleness is deferred in v2 — placeholder signal (golden normalizes it)
-    push('stale', cap, 0, 'DEFERRED');
+
+    // staleness (v1 evaluate): real base-ref/scope evaluation.
+    let staleInfo = notApplicableStaleness();
+    let staleCount = 0;
+    if (input.git !== undefined && input.root !== undefined) {
+      const specRel =
+        (entry.fileName.startsWith('llmanspec/') ? '' : 'llmanspec/specs/') + entry.fileName;
+      const evalResult = evaluateStaleness({
+        git: input.git,
+        root: input.root,
+        specRel,
+        scope: entry.doc.header.scope?.split(',').map((x) => x.trim()) ?? [],
+        baseRefEnv: process.env.LLMANSPEC_BASE_REF,
+      });
+      staleInfo = evalResult.info;
+      staleCount = staleInfo.status === 'OK' || staleInfo.status === 'NOTAPPLICABLE' ? 0 : 1;
+    }
+    push('stale', cap, staleCount, staleInfo.status === 'NOTAPPLICABLE' ? '' : staleInfo.status);
   }
 
   const failed = sweep.verdicts.filter((v) => !v.ok);
@@ -96,13 +115,13 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     'locked',
     '-',
     0,
-    `${boundChangeCount} bound change(s); inspect with \`llman-sdd change diff <id>\``,
+    `${boundChangeCount} bound change(s); inspect with \`llman sdd change diff <id>\``,
   );
   push(
     'validate',
     '-',
     failed.length,
-    failed.length > 0 ? 'validate --all failed; run `llman-sdd validate --all` for details' : 'ok',
+    failed.length > 0 ? 'validate --all failed; run `llman sdd validate --all` for details' : 'ok',
   );
 
   const warningCount = signals

package/src/spec/authoring.ts

@@ -0,0 +1,206 @@
+/**
+ * Programming-style spec authoring helpers (r41-r43, v1 parity):
+ * append rules / acceptance scenarios, resolve req ids, dedupe conflicts.
+ * Appends are text-level so existing file content (formatting, comments)
+ * stays untouched.
+ */
+
+import type { CapabilityDoc } from './ir.ts';
+
+const RULE_KEYWORDS = ['MUST', 'SHALL', '必须', '不得', '禁止'] as const;
+
+export class AuthoringError extends Error {}
+
+export interface SpecEntryLike {
+  fileName: string;
+  doc: CapabilityDoc;
+}
+
+export interface WriteIo {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  writeText(path: string, content: string): void;
+}
+
+function keywordsOf(content: string): {
+  scenario: string;
+  given: string;
+  when: string;
+  thenText: string;
+} {
+  return content.includes('功能:')
+    ? { scenario: '场景', given: '假如', when: '当', thenText: '那么' }
+    : { scenario: 'Scenario', given: 'Given', when: 'When', thenText: 'Then' };
+}
+
+function assertRuleWording(statement: string): void {
+  if (!RULE_KEYWORDS.some((k) => statement.includes(k))) {
+    throw new AuthoringError(
+      `statement must contain a rule keyword (${RULE_KEYWORDS.join('/')}): ${statement}`,
+    );
+  }
+}
+
+function findReq(
+  entries: readonly SpecEntryLike[],
+  reqId: string,
+): { entry: SpecEntryLike; scenarioName: string; statement: string } | null {
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      if (scenario.reqIds.includes(reqId) && scenario.classification === 'human') {
+        return { entry, scenarioName: scenario.name, statement: scenario.statement };
+      }
+    }
+  }
+  return null;
+}
+
+/** v1 parity: only @human (rule) req ids participate in the dedupe registry. */
+export function ruleReqIds(entries: readonly SpecEntryLike[]): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      if (scenario.classification === 'human') {
+        for (const id of scenario.reqIds) ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
+export function allReqIds(entries: readonly SpecEntryLike[]): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      for (const id of scenario.reqIds) ids.add(id);
+    }
+  }
+  return ids;
+}
+
+export interface AddReqOpts {
+  capability: string;
+  reqId: string;
+  title: string;
+  statement: string;
+}
+
+/** Append `@req:<id> @human` rule scenario to `<capability>.feature` (r41). */
+export function addReq(
+  io: WriteIo,
+  specsRoot: string,
+  entries: readonly SpecEntryLike[],
+  opts: AddReqOpts,
+): string {
+  const path = `${specsRoot}/${opts.capability}.feature`;
+  if (!io.exists(path)) throw new AuthoringError(`spec not found: ${path}`);
+  if (allReqIds(entries).has(opts.reqId)) {
+    throw new AuthoringError(`req id already in use: ${opts.reqId}`);
+  }
+  assertRuleWording(opts.statement);
+  const kw = keywordsOf(io.readText(path));
+  const block = `\n  @req:${opts.reqId} @human\n  ${kw.scenario}: ${opts.title}\n    ${opts.statement}\n`;
+  io.writeText(path, `${io.readText(path).replace(/\n+$/u, '')}${block}`);
+  return path;
+}
+
+export interface AddScenarioOpts {
+  capability: string;
+  reqId: string;
+  scenarioId: string;
+  given?: string;
+  when: string;
+  thenText: string;
+}
+
+/** Append `@req:<id> @executable` acceptance scenario (r42). */
+export function addScenario(
+  io: WriteIo,
+  specsRoot: string,
+  entries: readonly SpecEntryLike[],
+  opts: AddScenarioOpts,
+): string {
+  const path = `${specsRoot}/${opts.capability}.feature`;
+  if (!io.exists(path)) throw new AuthoringError(`spec not found: ${path}`);
+  if (findReq(entries, opts.reqId) === null) {
+    throw new AuthoringError(`req id not found: ${opts.reqId}`);
+  }
+  const kw = keywordsOf(io.readText(path));
+  const givenLine =
+    opts.given !== undefined && opts.given !== '' ? `    ${kw.given} ${opts.given}\n` : '';
+  const block =
+    `\n  @req:${opts.reqId} @executable\n  ${kw.scenario}: ${opts.scenarioId}\n` +
+    `${givenLine}    ${kw.when} ${opts.when}\n    ${kw.thenText} ${opts.thenText}\n`;
+  io.writeText(path, `${io.readText(path).replace(/\n+$/u, '')}${block}`);
+  return path;
+}
+
+export interface ResolvedReq {
+  reqId: string;
+  capability: string;
+  title: string;
+  statement: string;
+  harness: string[];
+}
+
+/** Resolve an rN to capability/statement plus bound harness scenarios (r43). */
+export function resolveReq(entries: readonly SpecEntryLike[], reqId: string): ResolvedReq | null {
+  const rule = findReq(entries, reqId);
+  if (rule === null) return null;
+  const capability =
+    rule.entry.doc.header.capability ?? rule.entry.fileName.replace(/\.feature$/u, '');
+  const harness: string[] = [];
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      if (scenario.classification === 'executable' && scenario.reqIds.includes(reqId)) {
+        harness.push(`${entry.fileName}:${scenario.name}`);
+      }
+    }
+  }
+  return { reqId, capability, title: rule.scenarioName, statement: rule.statement, harness };
+}
+
+export interface DedupePlanItem {
+  reqId: string;
+  keepFile: string;
+  remapFile: string;
+  newReqId: string;
+}
+
+/**
+ * Plan (and optionally apply) a re-map of globally duplicated rN ids: the
+ * first file keeps the id, later files get the next free id (r43).
+ */
+export function planDedupe(
+  entries: readonly SpecEntryLike[],
+  io: WriteIo,
+  specsRoot: string,
+  duplicates: readonly { reqId: string; files: string[] }[],
+): DedupePlanItem[] {
+  const used = ruleReqIds(entries);
+  let next = 1;
+  const fresh = (): string => {
+    while (used.has(`r${String(next)}`)) next += 1;
+    used.add(`r${String(next)}`);
+    return `r${String(next)}`;
+  };
+  const plan: DedupePlanItem[] = [];
+  for (const dup of duplicates) {
+    const [keep, ...rest] = dup.files;
+    for (const remapFile of rest) {
+      const newReqId = fresh();
+      if (keep !== undefined) {
+        plan.push({ reqId: dup.reqId, keepFile: keep, remapFile, newReqId });
+      }
+    }
+  }
+  for (const item of plan) {
+    // registry duplicates carry bare file names; accept already-rooted paths too
+    const path = item.remapFile.startsWith(`${specsRoot}/`)
+      ? item.remapFile
+      : `${specsRoot}/${item.remapFile}`;
+    const content = io.readText(path);
+    io.writeText(path, content.replaceAll(`@req:${item.reqId}`, `@req:${item.newReqId}`));
+  }
+  return plan;
+}

package/src/templates/embedded.ts

@@ -1,18 +1,19 @@
 /**
  * Embedded template table for single-file binaries.
  *
- * Bun <= 1.4.x has no working embedding mechanism (`assets` is a silent
- * no-op, `?raw`/`?asset` fail to resolve, `import.meta.glob` is unavailable
- * in compiled output), so templates are injected through the same build-time
- * `define` mechanism as LLMAN_SDD_VERSION: build-binary.ts collects
- * packages/core/templates into a root-relative path→content map and sets
- * process.env.LLMAN_SDD_EMBEDDED_TEMPLATES to that JSON. Bun inlines define
- * values as raw expressions — the JSON is a valid object literal, so in the
- * compiled binary the expression IS the table object itself, while a JSON
- * string reaches these callers through the same expression in other engines
- * or when force-set via env. Both forms are accepted below; every non-compiled
- * run (source, npm package, Node) leaves the define unset and falls back to
- * the real filesystem via TEMPLATES_ROOT.
+ * Bun 1.4.x offers no embedding that survives our Node >= 24 dual-runtime
+ * constraint: `with { type: "text" }` works in compiled output (probed on
+ * 1.4.2) but Node cannot load that attribute, and `assets`/`?raw`/`?asset`
+ * never land in the bundle — so templates are injected through the same
+ * build-time `define` mechanism as LLMAN_SDD_VERSION: build-binary.ts
+ * collects packages/core/templates into a root-relative path→content map and
+ * sets process.env.LLMAN_SDD_EMBEDDED_TEMPLATES to that JSON. Bun inlines
+ * define values as raw expressions — the JSON is a valid object literal, so
+ * in the compiled binary the expression IS the table object itself, while a
+ * JSON string reaches these callers through the same expression in other
+ * engines or when force-set via env. Both forms are accepted below; every
+ * non-compiled run (source, npm package, Node) leaves the define unset and
+ * falls back to the real filesystem via TEMPLATES_ROOT.
  */
 import type { TemplateIo } from './skills.ts';