@shanyucoder/flowgrid 0.1.0

package/adapters/fastapi/unitgen/runners/fast_unit_gen/cli.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+TOOLS_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(TOOLS_DIR))
+
+from fast_gen.plan import build_file_plan, render_template, repo_root  # noqa: E402
+from fast_gen.read_spec import read_spec_file  # noqa: E402
+from fast_gen.write_files import _package_version, _reject_symlinks, _safe_target  # noqa: E402
+
+UNIT_TEMPLATES = Path(__file__).resolve().parents[2] / "templates"
+
+def dry_cmd(spec: str, force: bool = False) -> None:
+  _run(spec, dry_run=True, force=force)
+
+
+def write_cmd(spec: str, force: bool = False) -> None:
+  _run(spec, dry_run=False, force=force)
+
+
+def _run(spec: str, *, dry_run: bool, force: bool) -> None:
+  spec_data, spec_path, feature_dir = read_spec_file(spec)
+  plan = build_file_plan(spec_data, force=force)
+  root = repo_root()
+  manifest_path = feature_dir / "generated" / "unit.manifest.json"
+  _reject_symlinks(manifest_path)
+  prior: dict = {}
+  if manifest_path.exists():
+    try:
+      loaded = json.loads(manifest_path.read_text(encoding="utf-8"))
+      if loaded.get("schemaVersion") == 2:
+        prior = loaded
+    except (OSError, json.JSONDecodeError):
+      pass
+
+  outputs: list[dict] = []
+  entity_counts = {
+    ctx["entity_snake"]: sum(
+      other["entity_snake"] == ctx["entity_snake"] for other in plan["contexts"]
+    )
+    for ctx in plan["contexts"]
+  }
+  for ctx in plan["contexts"]:
+    stem = ctx["entity_snake"]
+    if entity_counts[stem] > 1:
+      stem = f"{ctx['module_package']}_{stem}"
+    rel = f"tests/unit/test_{stem}_service.py"
+    content = render_template("test_service.py.j2", ctx, templates_dir=UNIT_TEMPLATES)
+    outputs.append({
+      "relativePath": rel,
+      "target": _safe_target(root, rel),
+      "content": content,
+      "sha256": hashlib.sha256(content.encode("utf-8")).hexdigest(),
+      "template": "test_service.py.j2",
+      "layer": "service-test",
+      "entity": ctx["entity"],
+      "module": ctx["module"],
+    })
+  paths = [item["relativePath"] for item in outputs]
+  duplicates = sorted({item for item in paths if paths.count(item) > 1})
+  if duplicates:
+    raise ValueError(f"Duplicate generated unit output paths: {', '.join(duplicates)}")
+
+  prior_files = prior.get("files") or {}
+  for item in outputs:
+    target = item["target"]
+    if not target.exists():
+      item["status"] = "would-write"
+      continue
+    existing_hash = hashlib.sha256(target.read_bytes()).hexdigest()
+    if existing_hash == item["sha256"]:
+      item["status"] = "unchanged"
+    elif prior_files.get(item["relativePath"], {}).get("sha256") == existing_hash:
+      item["status"] = "would-write"
+    elif force:
+      item["status"] = "would-force"
+    else:
+      item["status"] = "conflict"
+
+  print(f"fast-unit-gen: entities={len(plan['contexts'])}")
+  for item in outputs:
+    status = item["status"]
+    if not dry_run and status in ("would-write", "would-force"):
+      status = "write" if status == "would-write" else "force"
+    print(f"  {status}: {item['relativePath']}")
+  conflicts = [item for item in outputs if item["status"] == "conflict"]
+  if conflicts:
+    print("Blocked: unit files have unmanaged or locally modified conflicts; use --force to overwrite.", file=sys.stderr)
+    raise SystemExit(2)
+  if dry_run:
+    return
+
+  for item in outputs:
+    if item["status"] != "unchanged":
+      item["target"].parent.mkdir(parents=True, exist_ok=True)
+      item["target"].write_text(item["content"], encoding="utf-8")
+  manifest = {
+    "schemaVersion": 2,
+    "packageVersion": _package_version(),
+    "generator": "fastapi-unitgen",
+    "spec": str(spec_path),
+    "entities": [
+      {"module": ctx["module"], "entity": ctx["entity"]}
+      for ctx in plan["contexts"]
+    ],
+    "files": {
+      item["relativePath"]: {
+        "sha256": item["sha256"],
+        "template": item["template"],
+        "layer": item["layer"],
+        "entity": item["entity"],
+        "module": item["module"],
+      }
+      for item in outputs
+    },
+  }
+  manifest_path.parent.mkdir(parents=True, exist_ok=True)
+  manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+  print(f"  manifest: {manifest_path}")
+
+
+def resolve_spec_paths(spec: str | None, id_val: str | None) -> list[str]:
+  if spec:
+    return [spec]
+  if not id_val:
+    print("Error: --spec or --id required", file=sys.stderr)
+    sys.exit(1)
+  
+  import subprocess
+  script = TOOLS_DIR.parents[1] / "shared" / "resolve-cli.mjs"
+  try:
+    res = subprocess.run(
+      ["node", str(script), str(repo_root()), id_val, "api-codegen"],
+      capture_output=True, text=True, check=True
+    )
+    data = json.loads(res.stdout)
+    if not data.get("success"):
+      print(f"fast-unit-gen: FAIL --id {id_val}: {data.get('error')}", file=sys.stderr)
+      sys.exit(1)
+    
+    paths = data.get("paths", [])
+    notes = data.get("notes", [])
+    kind = data.get("kind", "unknown")
+    
+    for note in notes:
+      print(f"  note: {note}")
+    if not paths:
+      print(f"Error: --id {id_val}: no codegen specs", file=sys.stderr)
+      sys.exit(1)
+      
+    print(f"fast-unit-gen: --id {id_val} → {len(paths)} spec(s) ({kind})")
+    return paths
+  except Exception as e:
+    print(f"Error resolving --id {id_val}: {e}", file=sys.stderr)
+    sys.exit(1)
+
+def main() -> None:
+  parser = argparse.ArgumentParser(description="FastAPI unit test codegen")
+  subparsers = parser.add_subparsers(dest="command", required=True)
+  for command in ("dry", "write"):
+    child = subparsers.add_parser(command)
+    child.add_argument("--spec", required=False)
+    child.add_argument("--id", required=False)
+    child.add_argument("--force", action="store_true")
+  args = parser.parse_args()
+  
+  paths = resolve_spec_paths(getattr(args, "spec", None), getattr(args, "id", None))
+  
+  failed = 0
+  for spec_path in paths:
+    try:
+      _run(spec_path, dry_run=args.command == "dry", force=getattr(args, "force", False))
+      if len(paths) > 1:
+        print("")
+    except Exception as e:
+      failed += 1
+      print(f"fast-unit-gen: FAIL {spec_path}: {e}", file=sys.stderr)
+
+  if failed > 0:
+    sys.exit(1)
+
+if __name__ == "__main__":
+  main()

package/adapters/fastapi/unitgen/runners/generate

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+export PYTHONPATH="${ROOT}/codegen/runners:${ROOT}/unitgen/runners:${ROOT}/registries:${ROOT}/tools:${ROOT}/src"
+exec "${ROOT}/.venv/bin/python" -m fast_unit_gen.cli "$@"

package/adapters/fastapi/unitgen/runners/validate-registry.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { access, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const target = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const adapter = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+async function exists(file) {
+  try {
+    await access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const registryPath = path.join(target, 'registries/unit-test.registry.json')
+  const registry = JSON.parse(await readFile(registryPath, 'utf8'))
+  const errors = []
+  if (!registry.version || !registry.layers) {
+    errors.push('registry requires version and layers')
+  }
+  for (const [layer, definition] of Object.entries(registry.layers ?? {})) {
+    if (!definition.template) {
+      errors.push(`${layer}: template missing`)
+      continue
+    }
+    const candidates = [
+      path.join(adapter, 'templates', definition.template),
+      path.join(adapter, '../codegen/templates', definition.template),
+    ]
+    if (!(await Promise.any(candidates.map(async (candidate) => {
+      if (!(await exists(candidate))) throw new Error('missing')
+      return true
+    })).catch(() => false))) {
+      errors.push(`${layer}: packaged template missing: ${definition.template}`)
+    }
+  }
+  if (errors.length) throw new Error(errors.join('\n'))
+  console.log(`fastapi-unit.registry v${registry.version}: OK`)
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/adapters/fastapi/unitgen/templates/test_service.py.j2

@@ -0,0 +1,12 @@
+import pytest
+
+from app.modules.{{ module_kebab }}.{{ entity_snake }}.services.search_service import {{ entity_pascal }}SearchService
+from app.modules.{{ module_kebab }}.{{ entity_snake }}.schemas.request import {{ entity_pascal }}SearchRequest
+
+
+@pytest.mark.asyncio
+async def test_{{ entity_snake }}_search_returns_items():
+  service = {{ entity_pascal }}SearchService()
+  items, total = await service.search({{ entity_pascal }}SearchRequest())
+  assert total >= 0
+  assert isinstance(items, list)

package/adapters/laravel/codegen/runners/README.md

@@ -0,0 +1,45 @@
+# API codegen (`api-gen`)
+
+Mirror `portal:gen` — đọc `01-backend-spec.yaml`, map tags qua `registries/codegen.registry.json`, sinh lệnh `php artisan m:*` / `add:*`, stub Service, `generated/codegen.manifest.json` + `HANDOFF.md`.
+
+Chạy từ **repo root**:
+
+```bash
+# Validate tag registry
+pnpm api:registry
+
+# Gate sau /grill-api-spec
+pnpm api:gen:dry --spec docs/features/{slug}/01-backend-spec.yaml
+
+# Grill cập nhật codegen.commands + manifest + HANDOFF vào feature/generated/
+pnpm api:gen:dry --spec docs/features/{slug}/01-backend-spec.yaml --write-spec
+
+# /api-code — thực thi generators (cần approval.status: approved)
+pnpm api:gen --spec docs/features/{slug}/01-backend-spec.yaml --write-spec
+```
+
+| Flag | Mô tả |
+|------|--------|
+| `--dry-run` | Validate + in plan + tag plan, không chạy artisan |
+| `--write-spec` | Ghi `codegen.commands[]`, `generated/codegen.manifest.json`, `HANDOFF.md` |
+| `--plan-only` | Ghi HANDOFF, không chạy artisan |
+| `--force` | Chạy lại artisan dù module/model/controller đã tồn tại |
+
+Khi chạy lại, script **phân tích `src/`** rồi chỉ sinh lệnh còn thiếu:
+
+| Đã có | Hành vi |
+|--------|---------|
+| `Modules/{M}/module.json` | Không gọi `m:module` |
+| `app/Models/{Platform\|Tenant}/{E}.php` | Không gọi `m:model` (`--shared-model=no` trên wizard) |
+| Controller + route wired | Không gọi wizard; dùng `add:action` cho endpoint còn thiếu |
+| Tests | `m:module-test --type=controller --class={E}` nếu chỉ thiếu controller test |
+
+`--force` → thêm `--force` / `--yes` / `--overwrite-controller=yes` theo `make_help.md`.
+
+| Output | Mô tả |
+|--------|--------|
+| `registries/codegen.registry.json` | Tag → artisan command / HANDOFF phase (tham khảo Portal registry) |
+| `generated/codegen.manifest.json` | Tag plan, commands, manual items — agent đọc trước HANDOFF |
+| `generated/HANDOFF.md` | Checklist `#manual-*` sau khi generators chạy |
+
+Extracts: `.cursor/extracts/api-codegen-tags.md`, `api-codegen-readiness.md`

package/adapters/laravel/codegen/runners/generate.mjs

@@ -0,0 +1,296 @@
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { readSpecFile, writeSpecFile } from './lib/read-spec.mjs'
+import { buildCommandPlan, enrichSpecCodegen } from './lib/plan.mjs'
+import { loadCodegenRegistry } from './lib/codegen-registry.mjs'
+import { buildTagPlanWithRegistry } from './lib/tag-plan.mjs'
+import { validateSpec } from './lib/validate.mjs'
+import { runCommandPlan } from './lib/exec-artisan.mjs'
+import { writeServiceStubs } from './lib/stub-services.mjs'
+import { buildCodegenManifest, writeCodegenManifest } from './lib/write-manifest.mjs'
+import { renderHandoffMarkdown, writeHandoff } from './lib/write-handoff.mjs'
+import {
+  adapterRoot,
+  resolveLaravelProject
+} from '../../shared/project.mjs'
+
+const project = resolveLaravelProject()
+const laravelRoot = project.laravelRoot
+
+import { resolveHubId, resolveBackendSpecPaths } from '../../../shared/resolve-hub-id.mjs'
+import { mergeI18nFlat } from '../../../shared/i18n-merge.mjs'
+
+/**
+ * @param {string[]} argv
+ */
+function parseArgs(argv) {
+  const options = { dryRun: false, writeSpec: false, spec: null, execute: true, force: false, id: null }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--dry' || arg === '--dry-run') options.dryRun = true
+    else if (arg === '--write-spec') options.writeSpec = true
+    else if (arg === '--plan-only') options.execute = false
+    else if (arg === '--force') options.force = true
+    else if (arg === '--id') options.id = argv[++i]
+    else if (arg === '--spec') options.spec = argv[++i]
+    else if (!arg.startsWith('-') && !options.spec && !options.id) options.spec = arg
+  }
+
+  if (!options.spec && !options.id) {
+    throw new Error(
+      'Usage: pnpm api:gen --spec …/api/<seq>/01-backend-spec.yaml OR --id CMP-XXX'
+    )
+  }
+
+  return options
+}
+
+/** @param {object} spec @param {Record<string, unknown>} registry */
+function shouldRunUnitGen(spec, registry) {
+  if ((spec.tags ?? []).includes('#gen:test-unit')) {
+    return true
+  }
+
+  const profile = spec.codegen?.profile ?? 'crud-standard'
+  const defaults = registry.profiles?.[profile]?.defaultGenTags ?? []
+
+  return defaults.includes('#gen:test-unit')
+}
+
+/** @param {string} specFile @param {{ force?: boolean }} options */
+function runUnitGen(specFile, options) {
+  const args = [path.join(adapterRoot, 'unitgen/runners/generate.mjs'), '--spec', specFile]
+  if (options.force) {
+    args.push('--force')
+  }
+
+  console.log('\napi-gen: running api:unit-gen...')
+  const result = spawnSync(process.execPath, args, {
+    cwd: laravelRoot,
+    stdio: 'inherit',
+    env: process.env
+  })
+
+  if (result.status !== 0) {
+    throw new Error('api:unit-gen failed after api:gen')
+  }
+}
+
+function printTagPlan(tagPlan) {
+  if (!tagPlan.length) return
+  console.log('\nTag plan:')
+  for (const entry of tagPlan) {
+    const detail = entry.artisan ?? (entry.handoffTopic ? `handoff:${entry.handoffTopic}` : entry.status)
+    console.log(`  ${entry.tag} [${entry.phase}/${entry.status}] → ${detail}`)
+  }
+}
+
+async function resolveSpecPaths(options) {
+  if (options.id) {
+    const resolved = resolveHubId(laravelRoot, options.id, 'api-codegen')
+    for (const n of resolved.notes) console.warn(`  note: ${n}`)
+    if (!resolved.paths.length) {
+      throw new Error(`--id ${options.id}: no 01-backend-spec.yaml under docs hub`)
+    }
+    console.log(`api-gen: --id ${options.id} → ${resolved.paths.length} spec(s) (${resolved.kind})`)
+    return resolved.paths
+  }
+  if (options.spec) {
+    return resolveBackendSpecPaths(options.spec)
+  }
+  throw new Error('No --spec or --id provided.')
+}
+
+async function generateOne(options, registry, specPath) {
+  const { spec, specFile, featureDir } = await readSpecFile(specPath)
+
+  const validation = validateSpec(spec, {
+    requireApproved: !options.dryRun && options.execute,
+    registry
+  })
+  const plan = buildCommandPlan(spec, { repoRoot: laravelRoot, force: options.force })
+  const { tagPlan } = await buildTagPlanWithRegistry(spec, plan)
+
+  console.log(`api-gen: module=${plan.ctx.module} entity=${plan.ctx.entity} profile=${plan.ctx.profile}`)
+  console.log(`  target: ${laravelRoot} (${project.profile})`)
+  console.log(`  spec: ${specFile}`)
+  console.log(`  registry: ${registry.registryPath}`)
+  if (options.dryRun) console.log('  mode: dry-run')
+  if (options.force) console.log('  mode: force (overwrite existing via --force/--yes)')
+
+  const analysis = plan.analysis
+  if (analysis && !options.force) {
+    const existingLayers = Object.entries(analysis.files)
+      .filter(([, v]) => v)
+      .map(([layer]) => layer)
+    if (existingLayers.length) {
+      console.log(`  workspace: ${existingLayers.join(', ')} already present`)
+    }
+    if (analysis.controllerExists && analysis.controllerComplete) {
+      console.log('  controller: fully wired for spec endpoints')
+    } else if (analysis.controllerExists && Object.values(analysis.pendingWire).some(Boolean)) {
+      const pending = Object.entries(analysis.pendingWire)
+        .filter(([, v]) => v)
+        .map(([k]) => k)
+      console.log(`  controller: pending wire — ${pending.join(', ')}`)
+    }
+  }
+
+  if (validation.warnings.length) {
+    console.log('\nWarnings:')
+    for (const w of validation.warnings) console.log(`  ⚠ ${w}`)
+  }
+
+  if (validation.errors.length) {
+    console.error('\nErrors:')
+    for (const e of validation.errors) console.error(`  ✗ ${e}`)
+    throw new Error('Validation failed')
+  }
+
+  console.log('\nCommand plan:')
+  if (plan.commands.length === 0) {
+    console.log('  _(none — all layers exist or skipped)_')
+  }
+  for (const line of plan.artisanLines) {
+    console.log(`  php artisan ${line.replace(/^php artisan\s+/, '')}`)
+  }
+
+  if (plan.skipped?.length) {
+    console.log('\nSkipped (already exist):')
+    for (const item of plan.skipped) {
+      console.log(`  skip: ${item.id} — ${item.path}`)
+    }
+  }
+
+  printTagPlan(tagPlan)
+
+  const manifest = buildCodegenManifest({
+    spec,
+    specFile,
+    plan,
+    tagPlan,
+    registry,
+    dryRun: options.dryRun
+  })
+
+  const handoff = renderHandoffMarkdown({
+    spec,
+    specFile,
+    plan,
+    tagPlan,
+    dryRun: options.dryRun || !options.execute
+  })
+
+  if (options.dryRun || !options.execute) {
+    if (options.writeSpec) {
+      enrichSpecCodegen(spec, { repoRoot: laravelRoot, force: options.force })
+      await writeSpecFile(specFile, spec)
+      console.log('\nUpdated codegen.commands in spec')
+
+      const manifestPath = await writeCodegenManifest(featureDir, manifest, { dryRun: false })
+      console.log(`Wrote ${manifestPath}`)
+
+      const handoffPath = await writeHandoff(featureDir, handoff, { dryRun: false })
+      console.log(`Wrote ${handoffPath}`)
+    } else if (!options.dryRun) {
+      await writeHandoff(featureDir, handoff, { dryRun: false })
+      console.log(`\nWrote ${path.join(featureDir, 'generated/HANDOFF.md')}`)
+    }
+    console.log('\napi-gen:dry OK')
+    return
+  }
+
+  const commandResults = await runCommandPlan(plan.commands, {
+    dryRun: false,
+    stopOnError: true
+  })
+
+  const skippedResults = (plan.skipped ?? []).map((item) => ({
+    ...item,
+    code: 0,
+    stdout: `[skipped] ${item.reason}: ${item.path}`,
+    stderr: ''
+  }))
+  const allResults = [...skippedResults, ...commandResults]
+
+  const failed = commandResults.find((r) => r.code !== 0)
+  if (failed) {
+    console.error(`\nCommand failed: ${failed.id}`)
+    console.error(failed.stderr || failed.stdout)
+    throw new Error('Command execution failed')
+  }
+
+  const serviceStubs = await writeServiceStubs(spec, featureDir, {
+    dryRun: false,
+    laravelRoot
+  })
+
+  enrichSpecCodegen(spec, { repoRoot: laravelRoot, force: options.force })
+  if (options.writeSpec) {
+    await writeSpecFile(specFile, spec)
+  }
+
+  const finalManifest = buildCodegenManifest({
+    spec,
+    specFile,
+    plan,
+    tagPlan,
+    registry,
+    commandResults: allResults,
+    serviceStubs,
+    dryRun: false
+  })
+
+  const manifestPath = await writeCodegenManifest(featureDir, finalManifest, { dryRun: false })
+  const handoffPath = await writeHandoff(
+    featureDir,
+    renderHandoffMarkdown({
+      spec,
+      specFile,
+      plan,
+      tagPlan,
+      commandResults: allResults,
+      serviceStubs
+    })
+  )
+
+  console.log(`\nWrote ${manifestPath}`)
+  console.log(`Wrote ${handoffPath}`)
+
+  if (shouldRunUnitGen(spec, registry)) {
+    runUnitGen(specFile, options)
+  }
+
+  if (spec.i18n) {
+    const localesDir = path.join(laravelRoot, 'lang')
+    const i18nFiles = mergeI18nFlat(spec.i18n, localesDir, options.dryRun)
+    for (const f of i18nFiles) {
+      console.log(`  ${options.dryRun ? '[dry] ' : 'write'}: ${path.relative(laravelRoot, f.path)} (+${f.keysAdded} keys)`)
+    }
+  }
+
+  console.log('api-gen complete — agent: finish #manual-* items in HANDOFF, then run tests')
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const registry = await loadCodegenRegistry(adapterRoot)
+  const specPaths = await resolveSpecPaths(options)
+
+  if (specPaths.length > 1) {
+    console.log(`api-gen: ${specPaths.length} spec(s) to process`)
+  }
+
+  for (const specPath of specPaths) {
+    await generateOne(options, registry, specPath)
+    if (specPaths.length > 1) console.log('')
+  }
+
+  process.exit(0)
+}
+
+main().catch((err) => {
+  console.error(err.message ?? err)
+  process.exit(1)
+})

package/adapters/laravel/codegen/runners/lib/codegen-registry.mjs

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+export const REGISTRY_REL = 'registries/codegen.registry.json'
+
+/** @type {Record<string, unknown> | null} */
+let cached = null
+
+export async function loadCodegenRegistry(root = repoRoot) {
+  if (cached) return cached
+  const registryPath = path.join(root, REGISTRY_REL)
+  const raw = JSON.parse(await readFile(registryPath, 'utf8'))
+  cached = { ...raw, registryPath: REGISTRY_REL }
+  return cached
+}
+
+/**
+ * @param {string} tag
+ * @param {Record<string, unknown>} registry
+ */
+export function resolveTagDefinition(tag, registry) {
+  const text = String(tag).trim()
+  if (registry.domainTags?.[text]) {
+    return { ...registry.domainTags[text], tag: text, match: 'exact-domain' }
+  }
+  if (registry.genTags?.[text]) {
+    return { ...registry.genTags[text], tag: text, match: 'exact-gen' }
+  }
+
+  for (const [prefix, rule] of Object.entries(registry.prefixRules ?? {})) {
+    if (text.startsWith(prefix)) {
+      const suffix = text.slice(prefix.length)
+      return { ...rule, tag: text, suffix, match: 'prefix', prefix }
+    }
+  }
+
+  const alias = registry.aliases?.[text.toLowerCase()]
+  if (alias) {
+    return resolveTagDefinition(alias, registry)
+  }
+
+  return { tag: text, phase: 'unknown', match: 'unknown' }
+}
+
+/**
+ * @param {string[]} tags
+ * @param {Record<string, unknown>} registry
+ */
+export function validateTagsAgainstRegistry(tags, registry) {
+  const warnings = []
+  for (const tag of tags ?? []) {
+    const def = resolveTagDefinition(tag, registry)
+    if (def.match === 'unknown') {
+      warnings.push(`Unknown tag "${tag}" — add to ${REGISTRY_REL} or fix typo`)
+    }
+  }
+  return warnings
+}