@llman-sdd/core 0.3.0 → 0.5.0

package/src/spec/migrateNative.ts

@@ -0,0 +1,167 @@
+/**
+ * Legacy → native spec migration (v1 tag-based flat layout → native `规则:`
+ * blocks with nested `场景:`). Pure text transform with IO injected by the
+ * caller. Used by `spec migrate-native` (interactive + --dry-run) and the
+ * in-repo one-shot migration.
+ *
+ * Parsing ALWAYS goes through the official @cucumber/gherkin parser
+ * (parseFeatureSource) — no hand-rolled line scanning; the legacy ROLE is
+ * derived from the tag set the official parser exposes per scenario.
+ */
+
+import { parseFeatureSource } from './parser.ts';
+
+export interface MigrateBlock {
+  reqIds: string[];
+  isRule: boolean;
+  skip: boolean;
+  title: string;
+  /** Statement description lines for rules; step [keyword,text] pairs for acceptances. */
+  descriptionLines: string[];
+  steps: { keyword: string; text: string }[];
+}
+
+export interface MigrateAnalysis {
+  blocks: MigrateBlock[];
+}
+
+export type MigrateResult =
+  | { ok: true; content: string; rules: number; scenarios: number }
+  | { ok: false; message: string };
+
+const REQ_TAG_RE = /^@?req:(r\d+)$/u;
+
+function tagsOf(tags: readonly { name: string }[]): {
+  reqIds: string[];
+  isRule: boolean;
+  skip: boolean;
+} {
+  const names = tags.map((t) => t.name);
+  const reqIds = names
+    .map((n) => n.match(REQ_TAG_RE)?.[1])
+    .filter((v): v is string => v !== undefined);
+  const isRule = names.some((n) => n === '@rule' || n === '@human');
+  const skip = names.some((n) => n === '@skip' || n === '@experimental');
+  return { reqIds, isRule, skip };
+}
+
+/**
+ * True when the source already uses the native layout (has at least one
+ * top-level `规则:` block). Uses the official parser.
+ */
+export function hasNativeRules(source: string): boolean {
+  try {
+    const { doc } = parseFeatureSource(source);
+    return (doc.feature?.children ?? []).some((c) => c.rule !== undefined);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Analyze a legacy source through the official parser: every top-level
+ * scenario becomes a block; its role comes from the tags, its body from the
+ * official description/step fields.
+ */
+export function analyzeLegacy(source: string): MigrateAnalysis | { ok: false; message: string } {
+  const { doc } = parseFeatureSource(source);
+  const blocks: MigrateBlock[] = [];
+  for (const child of doc.feature?.children ?? []) {
+    if (child.rule) {
+      // native source — nothing to migrate here; caller should skip
+      continue;
+    }
+    const sc = child.scenario;
+    if (!sc) continue;
+    const { reqIds, isRule, skip } = tagsOf(sc.tags);
+    blocks.push({
+      reqIds,
+      isRule,
+      skip,
+      title: sc.name,
+      descriptionLines: (sc.description ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== ''),
+      steps: sc.steps.map((s) => ({ keyword: s.keyword.trim(), text: s.text.trim() })),
+    });
+  }
+  return { blocks };
+}
+
+/** Strip `- ` list markers from a rule-statement line (legacy prose residue). */
+function stripBullet(line: string): string {
+  return line.replace(/^-\s+/u, '');
+}
+
+/**
+ * Migrate one legacy feature source to the native layout. Structural rules:
+ * rules keep file order; acceptances nest under the rule carrying their
+ * @req id (file order); acceptances without a matching rule stay top-level
+ * orphans. Non-scenario lines (headers/feature/comments) are NOT touched —
+ * the native output only emits tag/rule/scenario lines, so the preamble is
+ * reconstructed by the caller from the original file.
+ */
+export function migrateNativeSource(source: string): MigrateResult {
+  const analysis = analyzeLegacy(source);
+  if ('ok' in analysis) return { ok: false, message: analysis.message };
+
+  const { blocks } = analysis as MigrateAnalysis;
+  if (blocks.length === 0) {
+    return { ok: false, message: 'no legacy scenarios found (already native?)' };
+  }
+
+  // preamble: everything before the first top-level tag line (headers,
+  // feature line, comments) — cut textually, preserved verbatim.
+  const lines = source.split('\n');
+  let preEnd = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if ((lines[i] ?? '').startsWith('  @')) break;
+    preEnd = i + 1;
+  }
+  const preamble = lines.slice(0, preEnd);
+
+  const out: string[] = [...preamble];
+  let rules = 0;
+  let scenarios = 0;
+  const consumed = new Set<number>();
+
+  for (const b of blocks) {
+    if (!b.isRule) continue;
+    rules++;
+    out.push(`  @req:${b.reqIds[0] ?? ''}`);
+    out.push(`  规则: ${b.title}`);
+    for (const line of b.descriptionLines) {
+      const text = stripBullet(line);
+      if (text !== '') out.push(`    ${text}`);
+    }
+    for (const [ai, a] of blocks.entries()) {
+      if (a.isRule || consumed.has(ai)) continue;
+      if (!a.reqIds.some((rid) => b.reqIds.includes(rid))) continue;
+      consumed.add(ai);
+      scenarios++;
+      out.push('');
+      if (a.skip) out.push('    @skip');
+      out.push(`    场景: ${a.title}`);
+      for (const s of a.steps) out.push(`      ${s.keyword} ${s.text}`);
+    }
+  }
+  // Unbound acceptance scenarios (no matching rule) are emitted last at
+  // top level — native feature-level examples with no requirement handle.
+  // Under official Gherkin parsing they are absorbed into the preceding rule,
+  // which is their natural functional home; no special signal exists for them.
+  for (const [ai, a] of blocks.entries()) {
+    if (a.isRule || consumed.has(ai)) continue;
+    consumed.add(ai);
+    scenarios++;
+    out.push('');
+    if (a.skip) out.push('  @skip');
+    out.push(`  场景: ${a.title}`);
+    for (const s of a.steps) out.push(`    ${s.keyword} ${s.text}`);
+  }
+
+  if (rules === 0) {
+    return { ok: false, message: 'no legacy rule scenarios found (@req + @rule/@human)' };
+  }
+  return { ok: true, content: `${out.join('\n')}\n`, rules, scenarios };
+}

package/src/spec/parser.ts

@@ -1,19 +1,22 @@
 /**
  * Single-track capability .feature parsing (spec-parsing capability).
  *
- * Language fallback chain (r7): start with the `en` matcher — a
- * `# language:` header switches dialect automatically mid-scan; on failure
- * retry with the zh-CN matcher (Chinese keywords without a header); only then
- * surface a parse error. locale zh-Hans maps to gherkin zh-CN.
+ * Native v2 model: `功能:` → `规则:` blocks (requirement: title + free-form
+ * description + `@req:<id>` handle) → nested `场景:` (executable examples).
+ * Top-level `场景:` outside any rule become orphans. Legacy role tags
+ * (@human/@rule/@executable/@manual) are inert — the parser only reads
+ * `@req` (handle) and `@skip`/`@experimental` (runner opt-out). Files in the
+ * legacy flat layout must be migrated with `spec migrate-native`.
  */
 import { AstBuilder, GherkinClassicTokenMatcher, Parser } from '@cucumber/gherkin';
 import type { GherkinDocument } from '@cucumber/messages';
 
 import {
-  MUST_WORD_RE,
   type CapabilityDoc,
   type CapabilityHeader,
+  type RuleIR,
   type ScenarioIR,
+  type ScenarioStepKind,
   type SpecStructuralError,
 } from './ir.ts';
 
@@ -52,13 +55,14 @@ export function parseFeatureSource(source: string): { doc: GherkinDocument; lang
 const REQ_TAG_RE = /^@?req:(r\d+)$/u;
 
 /** Gherkin keyword (zh-CN + en) → step kind; And/But/* inherit via fallback. */
-function stepKeywordToKind(keyword: string): 'given' | 'when' | 'then' {
+function stepKeywordToKind(keyword: string): ScenarioStepKind {
   const kw = keyword.trim();
   if (/^(假如|Given)/iu.test(kw)) return 'given';
   if (/^(当|When)/iu.test(kw)) return 'when';
   if (/^(那么|Then)/iu.test(kw)) return 'then';
   return 'given';
 }
+
 const HEADER_RE = /^#\s*(capability|purpose|scope):\s*(.*)$/u;
 
 function extractHeader(source: string): CapabilityHeader {
@@ -75,37 +79,47 @@ function extractHeader(source: string): CapabilityHeader {
   return header;
 }
 
-function classify(tags: string[]): {
-  classification: ScenarioIR['classification'];
-  errors: SpecStructuralError[];
-} {
-  const errors: SpecStructuralError[] = [];
-  const has = (t: string): boolean => tags.includes(t);
-  const human = has('human');
-  const executable = has('executable');
-  const label = tags.join(',');
-
-  if (has('manual')) {
-    errors.push({
-      code: 'tag:manual-removed',
-      message: `@manual was removed in 0.3.0 — drop the tag (@human already carries the human-judgement semantics) (tags: ${label})`,
-    });
-  }
-  if (human && executable) {
-    errors.push({
-      code: 'tag:mutually-exclusive',
-      message: `@human 与 @executable 互斥(tags: ${label})`,
-    });
-  }
-  const classification: ScenarioIR['classification'] = human
-    ? 'human'
-    : executable
-      ? 'executable'
-      : 'unclassified';
-  return { classification, errors };
+interface RawTags {
+  names: string[]; // without leading '@'
+  reqId: string;
+}
+
+function parseTags(tags: readonly { name: string }[]): RawTags {
+  const names = tags.map((t) => t.name.replace(/^@/u, ''));
+  const req = tags.map((t) => t.name.match(REQ_TAG_RE)?.[1]).find((v): v is string => !!v);
+  return { names, reqId: req ?? '' };
+}
+
+function collectScenario(sc: {
+  tags: readonly { name: string }[];
+  name: string;
+  steps: readonly { keyword: string; text: string }[];
+}): ScenarioIR {
+  const { names, reqId: _ignored } = parseTags(sc.tags);
+  const skipTokens = new Set(['skip', 'experimental']);
+  const runnable = !names.some((n) => skipTokens.has(n));
+  const steps = sc.steps.map((s) => ({
+    kind: stepKeywordToKind(s.keyword),
+    text: s.text.trim(),
+  }));
+  return {
+    name: sc.name,
+    tags: names.filter(
+      (n) =>
+        !n.startsWith('req') &&
+        !skipTokens.has(n) &&
+        !n.startsWith('rule') &&
+        !n.startsWith('human') &&
+        !n.startsWith('executable'),
+    ),
+    runnable,
+    stepCount: steps.length,
+    steps,
+    statement: steps.map((s) => s.text).join('\n'),
+  };
 }
 
-/** Parse one capability .feature source into the single-track IR. */
+/** Parse one capability .feature source into the native single-track IR. */
 export function parseCapability(source: string, fileName = '<inline>'): CapabilityDoc {
   const errors: SpecStructuralError[] = [];
   const header = extractHeader(source);
@@ -118,56 +132,38 @@ export function parseCapability(source: string, fileName = '<inline>'): Capabili
   const { doc, language } = parseFeatureSource(source);
   const feature = doc.feature;
   const featureName = feature?.name ?? '';
-  const scenarios: ScenarioIR[] = [];
+  const rules: RuleIR[] = [];
+  const orphans: ScenarioIR[] = [];
 
   for (const child of feature?.children ?? []) {
     const rule = child.rule;
-    if (rule && rule.children.some((c) => c.scenario)) {
-      errors.push({
-        code: 'rule:nested-scenario',
-        message: `Rule 块内嵌场景被拒绝(rule: ${rule.name})`,
+    if (rule) {
+      const { names, reqId } = parseTags(rule.tags);
+      const description = (rule.description ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== '')
+        .join('\n');
+      const scenarios: ScenarioIR[] = [];
+      for (const rc of rule.children) {
+        if (rc.scenario) scenarios.push(collectScenario(rc.scenario));
+      }
+      rules.push({
+        reqId,
+        title: rule.name,
+        description,
+        scenarios,
+        tags: names.filter(
+          (n) => !n.startsWith('req') && !n.startsWith('rule') && !n.startsWith('human'),
+        ),
       });
       continue;
     }
     const scenario = child.scenario;
-    if (!scenario) continue;
-
-    const tags = scenario.tags.map((t) => t.name.replace(/^@/u, ''));
-    const reqIds = scenario.tags
-      .map((t) => t.name.match(REQ_TAG_RE)?.[1])
-      .filter((v): v is string => v !== undefined);
-
-    const kind = classify(tags);
-    errors.push(...kind.errors);
-
-    const description = (scenario.description ?? '')
-      .split('\n')
-      .map((l) => l.trim())
-      .filter((l) => l !== '');
-    const stepTexts = scenario.steps.map((s) => s.text.trim());
-    const statement = [...description, ...stepTexts].join('\n');
-    const steps = scenario.steps.map((s) => ({
-      kind: stepKeywordToKind(s.keyword),
-      text: s.text.trim(),
-    }));
-
-    if (kind.classification === 'human' && !MUST_WORD_RE.test(statement)) {
-      errors.push({
-        code: 'rule:missing-must-word',
-        message: `@human 规则场景描述必须含 MUST/SHALL(scenario: ${scenario.name})`,
-      });
+    if (scenario) {
+      orphans.push(collectScenario(scenario));
     }
-
-    scenarios.push({
-      name: scenario.name,
-      tags,
-      reqIds,
-      classification: kind.classification,
-      statement,
-      stepCount: stepTexts.length,
-      steps,
-    });
   }
 
-  return { fileName, header, featureName, language, scenarios, errors };
+  return { fileName, header, featureName, language, rules, orphans, errors };
 }

package/src/spec/reqRegistry.ts

@@ -1,7 +1,7 @@
 /**
- * Global rN registry (spec-parsing capability): @req:rN ids form a single
- * global namespace across all capability specs; duplicates are reported with
- * the conflicting file pairs.
+ * Global rN registry (spec-parsing capability): @req:rN ids on `规则:` blocks
+ * form a single global namespace across all capability specs; duplicates are
+ * reported with the conflicting file pairs.
  */
 import type { CapabilityDoc } from './ir.ts';
 
@@ -21,12 +21,11 @@ export function buildReqRegistry(
 ): ReqRegistry {
   const byId = new Map<string, string[]>();
   for (const { fileName, doc } of docs) {
-    for (const scenario of doc.scenarios) {
-      for (const reqId of scenario.reqIds) {
-        const files = byId.get(reqId) ?? [];
-        if (!files.includes(fileName)) files.push(fileName);
-        byId.set(reqId, files);
-      }
+    for (const rule of doc.rules) {
+      if (rule.reqId === '') continue;
+      const files = byId.get(rule.reqId) ?? [];
+      if (!files.includes(fileName)) files.push(fileName);
+      byId.set(rule.reqId, files);
     }
   }
   const duplicates: RegistryDuplicate[] = [];

package/src/templates/embedded.ts

@@ -1,19 +1,13 @@
 /**
  * Embedded template table for single-file binaries.
  *
- * 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.
+ * Compiled binaries receive the table through the same build-time define
+ * mechanism as the version (see apps/cli/src/cli-shared.ts — the define read
+ * lives at the CLI seam, core only receives already-resolved values). Bun
+ * inlines define values as raw expressions; both the JSON-string form and a
+ * pre-parsed object literal are accepted below. Every non-compiled run
+ * (source, npm package, Node) leaves the value unset and falls back to the
+ * real filesystem via TEMPLATES_ROOT.
  */
 import type { TemplateIo } from './skills.ts';
 
@@ -37,9 +31,9 @@ export function resolveEmbeddedTable(value: unknown): Record<string, string> | u
   return undefined;
 }
 
-/** Read the build-injected table; undefined when absent or malformed. */
-export function embeddedTemplates(): Record<string, string> | undefined {
-  return resolveEmbeddedTable(process.env.LLMAN_SDD_EMBEDDED_TEMPLATES);
+/** Resolve the caller-passed define value; undefined when absent or malformed. */
+export function embeddedTemplates(raw?: unknown): Record<string, string> | undefined {
+  return resolveEmbeddedTable(raw);
 }
 
 /**

package/src/templates/engine.ts

@@ -1,6 +1,6 @@
 /**
  * Template engine (init-generators capability, r17): nunjucks adapter with
- * minijinja-compatible semantics used by v1 — string-only globals, undefined
+ * minijinja-compatible semantics used by predecessor — string-only globals, undefined
  * renders empty (Lenient), nested `unit(id)` expansion capped at 32, and
  * trailing whitespace trimmed from the final product.
  */
@@ -22,22 +22,26 @@ export function renderWithUnits(
   units: UnitRegistry,
   vars: Record<string, string>,
   depth = 0,
+  opts: { throwOnUndefined?: boolean } = {},
 ): string {
   if (depth > MAX_UNIT_NESTING_DEPTH) {
     throw new Error(`unit nesting exceeded ${MAX_UNIT_NESTING_DEPTH}`);
   }
   // minijinja keep_trailing_newline=false: a single trailing newline of the
-  // template SOURCE is stripped before rendering (v1 parity). \r? first —
+  // template SOURCE is stripped before rendering (predecessor parity). \r? first —
   // stripping \n alone would strand a trailing \r for CRLF sources.
   const source = raw.replace(/\r?\n$/u, '');
-  const env = new nunjucks.Environment(null, { autoescape: false });
+  const env = new nunjucks.Environment(null, {
+    autoescape: false,
+    throwOnUndefined: opts.throwOnUndefined === true,
+  });
   for (const [key, value] of Object.entries(vars)) {
     env.addGlobal(key, value);
   }
   env.addGlobal('unit', (id: string): string => {
     const content = units.get(id);
     if (content === undefined) throw new MissingUnitError(id);
-    return renderWithUnits(content, units, vars, depth + 1);
+    return renderWithUnits(content, units, vars, depth + 1, opts);
   });
   return env.renderString(source, {});
 }
@@ -47,6 +51,7 @@ export function renderTemplate(
   raw: string,
   units: UnitRegistry,
   vars: Record<string, string>,
+  opts: { throwOnUndefined?: boolean } = {},
 ): string {
-  return renderWithUnits(raw, units, vars, 0).trimEnd();
+  return renderWithUnits(raw, units, vars, 0, opts).trimEnd();
 }

package/src/templates/locale.ts

@@ -1,6 +1,6 @@
 /**
  * Locale normalization + fallback chain (init-generators capability, r18).
- * Port of v1 config.rs normalize_locale / locale_fallbacks.
+ * Port of predecessor config.rs normalize_locale / locale_fallbacks.
  */
 export function normalizeLocale(value: string): string {
   const trimmed = value.trim();

package/src/templates/skills.ts

@@ -2,7 +2,7 @@ import type { SddConfig } from '../config/schema.ts';
 import { renderTemplate, type UnitRegistry } from './engine.ts';
 /**
  * Skills rendering + init orchestration (init-generators capability, r19).
- * Port of v1 templates.rs / update_skills.rs / init.rs semantics.
+ * Port of predecessor templates.rs / update_skills.rs / init.rs semantics.
  */
 import { localeFallbacks } from './locale.ts';
 
@@ -37,6 +37,7 @@ export const UNIT_FILES: readonly string[] = [
   'skills/ethics-governance.md',
   'spec/feature-contract.md',
   'skills/structured-protocol.md',
+  'skills/cli-footer.md',
   'workflow/archive-freeze-guidance.md',
 ];
 
@@ -48,7 +49,7 @@ export const ETHICS_KEYS: readonly string[] = [
   'ethics.escalation_policy',
 ];
 
-/** Framework-derived run_command (v1 config.rs effective_run_command). */
+/** Framework-derived run_command (predecessor config.rs effective_run_command). */
 export function effectiveRunCommand(bdd: NonNullable<SddConfig['bdd']>): string {
   if (bdd.run_command) return bdd.run_command;
   switch (bdd.framework ?? '') {
@@ -65,15 +66,13 @@ export function effectiveRunCommand(bdd: NonNullable<SddConfig['bdd']>): string
   }
 }
 
-/** All-string globals (v1 BTreeMap<String, String> semantics). */
+/** All-string globals (predecessor BTreeMap<String, String> semantics). */
 export function buildTemplateVars(config: SddConfig, version: string): Record<string, string> {
   const vars: Record<string, string> = { llman_version: version };
   if (config.bdd) {
     vars['bdd_enabled'] = 'true';
     vars['bdd_framework'] = config.bdd.framework ?? '';
-    if (config.bdd.feature_dir) vars['bdd_feature_dir'] = config.bdd.feature_dir;
     vars['bdd_run_command'] = effectiveRunCommand(config.bdd);
-    if (config.bdd.default_language) vars['bdd_default_language'] = config.bdd.default_language;
     if (config.bdd.verify_prompt) vars['bdd_verify_prompt'] = config.bdd.verify_prompt;
   }
   const extras = new Set<string>(config.extra_skills ?? []);