@vibe-forge/definition-core 0.9.1

package/AGENTS.md

@@ -0,0 +1,35 @@
+# Definition Core 包说明
+
+`@vibe-forge/definition-core` 承载 definition 领域共享语义 helper。
+
+## 什么时候先看这里
+
+- definition 的名称、标识、摘要推导不一致
+- remote rule reference 在不同包里的投影不一致
+- `definition-loader` 和 `workspace-assets` 之间需要共享 definition 领域 helper
+
+## 入口
+
+- `src/index.ts`
+  - definition 名称、标识、摘要、always 语义 helper
+  - remote rule reference 到 definition 的投影 helper
+- `__tests__/definition-core.spec.ts`
+
+## 当前边界
+
+- 本包负责：
+  - definition 名称解析
+  - spec / entity / skill 标识解析
+  - definition 摘要描述解析
+  - rule always 语义兼容
+  - remote rule reference 的 definition 投影
+- 本包不负责：
+  - 文档发现与读取
+  - prompt 文本拼装
+  - workspace asset 选择
+  - task 生命周期编排
+
+## 维护约定
+
+- 只放 definition 领域共享语义，不放通用路径工具，也不放 prompt builder。
+- 依赖保持轻量，优先只依赖 `@vibe-forge/types`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Vibe-Forge.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/__tests__/definition-core.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  createRemoteRuleDefinition,
+  isAlwaysRule,
+  isLocalRuleReference,
+  isPathLikeReference,
+  isRemoteRuleReference,
+  parseScopedReference,
+  resolveDefinitionName,
+  resolveDocumentDescription,
+  resolveDocumentName,
+  resolveEntityIdentifier,
+  resolveSkillIdentifier,
+  resolveSpecIdentifier
+} from '#~/index.js'
+
+describe('definition core helpers', () => {
+  it('prefers explicit document names and handles index files', () => {
+    expect(resolveDocumentName('/tmp/specs/index.md', '  explicit  ')).toBe('explicit')
+    expect(resolveDocumentName('/tmp/skills/example/SKILL.md', undefined, ['skill.md'])).toBe('example')
+  })
+
+  it('resolves spec, entity, and skill identifiers from conventional files', () => {
+    expect(resolveSpecIdentifier('/tmp/specs/my-spec/index.md')).toBe('my-spec')
+    expect(resolveEntityIdentifier('/tmp/project/.ai/entities/reviewer/README.md')).toBe('reviewer')
+    expect(resolveSkillIdentifier('/tmp/project/.ai/skills/research/SKILL.md')).toBe('research')
+  })
+
+  it('resolves definition names from explicit names, resolved names, and file paths', () => {
+    expect(resolveDefinitionName({
+      path: '/tmp/project/.ai/rules/base.md',
+      body: '',
+      attributes: {}
+    })).toBe('base')
+
+    expect(resolveDefinitionName({
+      path: '/tmp/project/.ai/specs/release/index.md',
+      body: '',
+      attributes: {},
+      resolvedName: 'demo/release'
+    }, ['index.md'])).toBe('demo/release')
+  })
+
+  it('resolves descriptions from explicit descriptions or the first non-empty body line', () => {
+    expect(resolveDocumentDescription('first line\nsecond line', ' explicit ', 'fallback')).toBe('explicit')
+    expect(resolveDocumentDescription('\nfirst line\nsecond line', undefined, 'fallback')).toBe('first line')
+    expect(resolveDocumentDescription('\n\n', undefined, 'fallback')).toBe('fallback')
+  })
+
+  it('supports rule always compatibility across always and alwaysApply', () => {
+    expect(isAlwaysRule({ always: true })).toBe(true)
+    expect(isAlwaysRule({ alwaysApply: true })).toBe(true)
+    expect(isAlwaysRule({ always: false, alwaysApply: true })).toBe(false)
+    expect(isAlwaysRule({})).toBe(false)
+  })
+
+  it('identifies local and remote rule references consistently', () => {
+    expect(isLocalRuleReference({ path: './rules/base.md' })).toBe(true)
+    expect(isLocalRuleReference({ type: 'local', path: './rules/base.md' })).toBe(true)
+    expect(isLocalRuleReference({ type: 'remote', tags: ['business'] })).toBe(false)
+
+    expect(isRemoteRuleReference({ type: 'remote', tags: ['business'] })).toBe(true)
+    expect(isRemoteRuleReference({ path: './rules/base.md' })).toBe(false)
+    expect(isRemoteRuleReference('rules/base.md')).toBe(false)
+  })
+
+  it('parses scoped references while excluding path-like values', () => {
+    expect(parseScopedReference('demo/release')).toEqual({ scope: 'demo', name: 'release' })
+    expect(parseScopedReference('./rules/base.md')).toBeUndefined()
+    expect(parseScopedReference('/abs/path/rule.md')).toBeUndefined()
+    expect(parseScopedReference('release.md')).toBeUndefined()
+    expect(parseScopedReference('demo/server.yaml', { pathSuffixes: ['.md', '.json', '.yaml', '.yml'] }))
+      .toBeUndefined()
+  })
+
+  it('detects path-like references with optional glob support', () => {
+    expect(isPathLikeReference('./rules/base.md')).toBe(true)
+    expect(isPathLikeReference('/abs/path/rule.md')).toBe(true)
+    expect(isPathLikeReference('rules/*.md', { allowGlob: true })).toBe(true)
+    expect(isPathLikeReference('demo/release')).toBe(false)
+    expect(isPathLikeReference('demo/server.yaml', { pathSuffixes: ['.md', '.json', '.yaml', '.yml'] })).toBe(true)
+  })
+
+  it('builds remote rule definitions with normalized descriptions and tags', () => {
+    expect(createRemoteRuleDefinition({
+      type: 'remote',
+      tags: [' business ', '', 'api-develop']
+    }, 1)).toEqual({
+      path: 'remote-rule-2.md',
+      body: [
+        'Remote knowledge base tags: business, api-develop',
+        'Knowledge base tags: business, api-develop',
+        'This rule comes from a remote knowledge base reference and does not correspond to a local file.'
+      ].join('\n'),
+      attributes: {
+        name: 'remote:business,api-develop',
+        description: 'Remote knowledge base tags: business, api-develop'
+      }
+    })
+  })
+
+  it('prefers explicit remote rule descriptions when present', () => {
+    expect(
+      createRemoteRuleDefinition({
+        type: 'remote',
+        tags: ['business'],
+        desc: 'Look up remote business knowledge when needed'
+      }, 0).attributes.description
+    ).toBe('Look up remote business knowledge when needed')
+  })
+})

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@vibe-forge/definition-core",
+  "version": "0.9.1",
+  "description": "Shared definition-domain helpers for Vibe Forge",
+  "imports": {
+    "#~/*.js": {
+      "__vibe-forge__": {
+        "default": "./src/*.ts"
+      },
+      "default": {
+        "import": "./dist/*.mjs",
+        "require": "./dist/*.js"
+      }
+    }
+  },
+  "exports": {
+    ".": {
+      "__vibe-forge__": {
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@vibe-forge/types": "^0.9.0"
+  },
+  "scripts": {
+    "test": "pnpm -C ../.. exec vitest run --workspace vitest.workspace.ts --project bundler packages/definition-core/__tests__"
+  }
+}

package/src/index.ts

@@ -0,0 +1,156 @@
+import { basename, dirname } from 'node:path'
+
+import type { Definition, LocalRuleReference, RemoteRuleReference, Rule, RuleReference } from '@vibe-forge/types'
+
+const stripExtension = (fileName: string) => fileName.replace(/\.[^/.]+$/, '')
+
+const hasAnySuffix = (value: string, suffixes: string[]) => suffixes.some(suffix => value.endsWith(suffix))
+
+export const parseScopedReference = (
+  value: string,
+  options: {
+    pathSuffixes?: string[]
+  } = {}
+) => {
+  const pathSuffixes = options.pathSuffixes ?? ['.md', '.json']
+
+  if (
+    value.startsWith('./') ||
+    value.startsWith('../') ||
+    value.startsWith('/') ||
+    hasAnySuffix(value, pathSuffixes)
+  ) {
+    return undefined
+  }
+
+  const separatorIndex = value.indexOf('/')
+  if (separatorIndex <= 0) return undefined
+
+  return {
+    scope: value.slice(0, separatorIndex),
+    name: value.slice(separatorIndex + 1)
+  }
+}
+
+export const isPathLikeReference = (
+  value: string,
+  options: {
+    pathSuffixes?: string[]
+    allowGlob?: boolean
+  } = {}
+) => {
+  const pathSuffixes = options.pathSuffixes ?? ['.md', '.json']
+  const allowGlob = options.allowGlob ?? false
+
+  return (
+    value.startsWith('./') ||
+    value.startsWith('../') ||
+    value.startsWith('/') ||
+    (allowGlob && value.includes('*')) ||
+    hasAnySuffix(value, pathSuffixes)
+  )
+}
+
+export const resolveDocumentName = (
+  path: string,
+  explicitName?: string,
+  indexFileNames: string[] = []
+) => {
+  const trimmedName = explicitName?.trim()
+  if (trimmedName) return trimmedName
+
+  const fileName = basename(path).toLowerCase()
+  if (indexFileNames.includes(fileName)) {
+    return basename(dirname(path))
+  }
+
+  return stripExtension(basename(path))
+}
+
+export const resolveSpecIdentifier = (path: string, explicitName?: string) => (
+  resolveDocumentName(path, explicitName, ['index.md'])
+)
+
+export const resolveEntityIdentifier = (path: string, explicitName?: string) => (
+  resolveDocumentName(path, explicitName, ['readme.md', 'index.json'])
+)
+
+export const resolveSkillIdentifier = (path: string, explicitName?: string) => (
+  resolveDocumentName(path, explicitName, ['skill.md'])
+)
+
+const getFirstNonEmptyLine = (text: string) =>
+  text
+    .split('\n')
+    .map(line => line.trim())
+    .find(Boolean)
+
+export const resolveDocumentDescription = (
+  body: string,
+  explicitDescription?: string,
+  fallbackName?: string
+) => {
+  const trimmedDescription = explicitDescription?.trim()
+  return trimmedDescription || getFirstNonEmptyLine(body) || fallbackName || ''
+}
+
+export const isAlwaysRule = (attributes: Pick<Rule, 'always' | 'alwaysApply'>) => (
+  attributes.always ?? attributes.alwaysApply ?? false
+)
+
+export const resolveDefinitionName = <T extends { name?: string }>(
+  definition: Definition<T>,
+  indexFileNames: string[] = []
+) => definition.resolvedName?.trim() || resolveDocumentName(definition.path, definition.attributes.name, indexFileNames)
+
+const toNonEmptyStringArray = (values: unknown): string[] => {
+  if (!Array.isArray(values)) return []
+
+  return values
+    .filter((value): value is string => typeof value === 'string')
+    .map(value => value.trim())
+    .filter(Boolean)
+}
+
+export const isLocalRuleReference = (value: RuleReference): value is LocalRuleReference => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    typeof (value as { path?: unknown }).path === 'string' &&
+    ((value as { type?: unknown }).type == null || (value as { type?: unknown }).type === 'local')
+  )
+}
+
+export const isRemoteRuleReference = (value: RuleReference): value is RemoteRuleReference => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    value.type === 'remote'
+  )
+}
+
+export const createRemoteRuleDefinition = (
+  rule: RemoteRuleReference,
+  index: number
+): Definition<Rule> => {
+  const tags = toNonEmptyStringArray(rule.tags)
+  const description = rule.desc?.trim() || (
+    tags.length > 0
+      ? `Remote knowledge base tags: ${tags.join(', ')}`
+      : 'Remote knowledge base rule reference'
+  )
+  const bodyParts = [
+    description,
+    tags.length > 0 ? `Knowledge base tags: ${tags.join(', ')}` : undefined,
+    'This rule comes from a remote knowledge base reference and does not correspond to a local file.'
+  ].filter((value): value is string => Boolean(value))
+
+  return {
+    path: `remote-rule-${index + 1}.md`,
+    body: bodyParts.join('\n'),
+    attributes: {
+      name: tags.length > 0 ? `remote:${tags.join(',')}` : `remote-rule-${index + 1}`,
+      description
+    }
+  }
+}