@vegastack/skills 0.4.0 → 0.6.0

package/skill/arch-guardian/scripts/schema-validate.mjs

@@ -1,63 +0,0 @@
-function pointer(root, reference) {
-  if (!reference.startsWith('#/')) throw new Error(`Only local JSON Schema references are supported: ${reference}`)
-  return reference.slice(2).split('/').reduce((value, key) => value?.[key.replaceAll('~1', '/').replaceAll('~0', '~')], root)
-}
-
-const same = (left, right) => JSON.stringify(left) === JSON.stringify(right)
-const typeOf = value => Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value
-const joinPath = (base, key) => `${base}/${String(key).replaceAll('~', '~0').replaceAll('/', '~1')}`
-const validDate = value => {
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
-  const [year, month, day] = value.split('-').map(Number)
-  const parsed = new Date(Date.UTC(year, month - 1, day))
-  return parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month - 1 && parsed.getUTCDate() === day
-}
-
-export function validateJsonSchema(schema, value) {
-  const errors = []
-  function validate(node, data, path = '$', quiet = false) {
-    const local = []
-    const add = message => local.push(`${path}: ${message}`)
-    if (node.$ref) return validate(pointer(schema, node.$ref), data, path, quiet)
-    if (node.const !== undefined && !same(data, node.const)) add(`must equal ${JSON.stringify(node.const)}`)
-    if (node.enum && !node.enum.some(item => same(item, data))) add(`must be one of ${node.enum.map(item => JSON.stringify(item)).join(', ')}`)
-    if (node.type) {
-      const allowed = Array.isArray(node.type) ? node.type : [node.type]
-      if (!allowed.includes(typeOf(data)) || (typeOf(data) === 'number' && !Number.isFinite(data))) add(`must be ${allowed.join(' or ')}`)
-    }
-    if (typeof data === 'string') {
-      if (node.minLength !== undefined && data.length < node.minLength) add(`must have length >= ${node.minLength}`)
-      if (node.pattern && !new RegExp(node.pattern).test(data)) add(`must match ${node.pattern}`)
-      if (node.format === 'date' && !validDate(data)) add('must be a real ISO calendar date (YYYY-MM-DD)')
-    }
-    if (typeof data === 'number' && node.minimum !== undefined && data < node.minimum) add(`must be >= ${node.minimum}`)
-    if (Array.isArray(data)) {
-      if (node.minItems !== undefined && data.length < node.minItems) add(`must contain at least ${node.minItems} item(s)`)
-      if (node.uniqueItems && new Set(data.map(item => JSON.stringify(item))).size !== data.length) add('must contain unique items')
-      if (node.items) data.forEach((item, index) => local.push(...validate(node.items, item, joinPath(path, index), true)))
-    }
-    if (data && typeof data === 'object' && !Array.isArray(data)) {
-      const keys = Object.keys(data)
-      if (node.minProperties !== undefined && keys.length < node.minProperties) add(`must contain at least ${node.minProperties} properties`)
-      for (const required of node.required ?? []) if (!(required in data)) local.push(`${joinPath(path, required)}: is required`)
-      for (const [key, child] of Object.entries(node.properties ?? {})) if (key in data) local.push(...validate(child, data[key], joinPath(path, key), true))
-      if (node.propertyNames) for (const key of keys) local.push(...validate(node.propertyNames, key, `${path} property ${JSON.stringify(key)}`, true))
-      const known = new Set(Object.keys(node.properties ?? {}))
-      for (const key of keys.filter(key => !known.has(key))) {
-        if (node.additionalProperties === false) local.push(`${joinPath(path, key)}: additional property is not allowed`)
-        else if (node.additionalProperties && typeof node.additionalProperties === 'object') local.push(...validate(node.additionalProperties, data[key], joinPath(path, key), true))
-      }
-    }
-    for (const child of node.allOf ?? []) local.push(...validate(child, data, path, true))
-    if (node.oneOf) {
-      const matches = node.oneOf.map(child => validate(child, data, path, true)).filter(result => result.length === 0).length
-      if (matches !== 1) add(`must match exactly one schema branch (matched ${matches})`)
-    }
-    if (node.not && validate(node.not, data, path, true).length === 0) add('must not match forbidden schema')
-    if (node.if && validate(node.if, data, path, true).length === 0 && node.then) local.push(...validate(node.then, data, path, true))
-    if (!quiet) errors.push(...local)
-    return local
-  }
-  validate(schema, value)
-  return errors
-}

package/skill/arch-guardian/scripts/validate-profile.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-import { readFile } from 'node:fs/promises'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { listFiles, readJsonYaml, resolveProfile } from './lib.mjs'
-import { validateJsonSchema } from './schema-validate.mjs'
-
-const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
-const architectureRoot = join(skillRoot, 'references', 'architecture')
-const schemaPath = join(skillRoot, 'assets', 'architecture-profile.schema.json')
-
-export async function canonicalRuleIds() {
-  const ids = new Set()
-  const duplicates = new Set()
-  for (const path of await listFiles(architectureRoot, file => file.endsWith('.md'))) {
-    const body = await readFile(path, 'utf8')
-    for (const match of body.matchAll(/\*\*([A-Z]+-[0-9]{3}) —/g)) {
-      if (ids.has(match[1])) duplicates.add(match[1])
-      ids.add(match[1])
-    }
-  }
-  if (duplicates.size) throw new Error(`Duplicate canonical rule IDs: ${[...duplicates].join(', ')}`)
-  return ids
-}
-
-// Collect every REQUIRED-* placeholder still present so a draft cannot be mistaken for
-// confirmed facts.
-function unconfirmedValues(value, path = '') {
-  if (typeof value === 'string') return value.startsWith('REQUIRED-') ? [path || '(root)'] : []
-  if (Array.isArray(value)) return value.flatMap((item, index) => unconfirmedValues(item, `${path}[${index}]`))
-  if (value && typeof value === 'object') return Object.entries(value).flatMap(([key, item]) => unconfirmedValues(item, path ? `${path}.${key}` : key))
-  return []
-}
-
-export async function validateProfile(path) {
-  let profile
-  try { profile = await readJsonYaml(path) } catch (error) {
-    return { profile: null, errors: [error.message] }
-  }
-  if (profile.schemaVersion === 2 || profile.schemaVersion === 3) {
-    return { profile, errors: [`schemaVersion ${profile.schemaVersion} is obsolete; run profile-tool.mjs migrate <profile> for a deterministic read-only v4 draft, then confirm project facts (v2 needs a fresh v4 profile from answers)`] }
-  }
-  const errors = []
-  const schema = JSON.parse(await readFile(schemaPath, 'utf8'))
-  for (const message of validateJsonSchema(schema, profile)) errors.push(message)
-  for (const location of unconfirmedValues(profile)) errors.push(`${location}: replace the REQUIRED placeholder with a confirmed fact`)
-  return { profile, errors }
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
-  const argument = process.argv.slice(2).find(value => !value.startsWith('-'))
-  let path = argument ? resolve(argument) : null
-  if (!path) {
-    const discovered = await resolveProfile(process.cwd())
-    if (!discovered) { console.error('error: no .vegastack/architecture.json (or legacy .yaml) profile found; pass a path explicitly'); process.exit(2) }
-    if (discovered.legacy) console.error(`deprecation: ${discovered.relative} uses the legacy .yaml name for a JSON document; rename to .vegastack/architecture.json`)
-    path = discovered.path
-  }
-  const json = process.argv.includes('--json')
-  const result = await validateProfile(path)
-  if (json) console.log(JSON.stringify({ path, valid: result.errors.length === 0, errors: result.errors }, null, 2))
-  else if (result.errors.length) for (const error of result.errors) console.error(`invalid profile: ${error}`)
-  else console.log(`validate-profile: valid ${path}`)
-  if (result.errors.length) process.exitCode = 1
-}

package/skill/arch-guardian/scripts/verify-corpus.mjs

@@ -1,136 +0,0 @@
-#!/usr/bin/env node
-import { readFile } from 'node:fs/promises'
-import { basename, dirname, join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { listFiles, pathExists, readJsonYaml } from './lib.mjs'
-import { canonicalRuleIds } from './validate-profile.mjs'
-
-let mermaid = null
-try {
-  const { JSDOM } = await import('jsdom')
-  const dom = new JSDOM('<!doctype html><html><body></body></html>')
-  globalThis.window = dom.window
-  globalThis.document = dom.window.document
-  mermaid = (await import('mermaid')).default
-  mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' })
-} catch {
-  // Installed copies have no development dependencies and use structural checks.
-}
-
-const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
-const references = join(skillRoot, 'references')
-const architectureRoot = join(references, 'architecture')
-const skillPath = join(skillRoot, 'SKILL.md')
-const skillBody = await readFile(skillPath, 'utf8')
-const chapters = await listFiles(architectureRoot, path => path.endsWith('.md'))
-const registry = await readJsonYaml(join(skillRoot, 'refresh', 'sources.json'))
-const sourceIds = new Set(registry.sources.map(source => source.id))
-const ruleIds = await canonicalRuleIds()
-const ruleModel = await readJsonYaml(join(references, 'rule-model.json'))
-const errors = []
-let diagrams = 0
-let normativeLines = 0
-
-const expectedReferences = new Set(['agent-product.md', 'ai-cost.md', 'ai-data-boundaries.md', 'ai-evals.md', 'connectors-sandbox.md', 'data-memory.md', 'delivery-operations.md', 'durable-execution.md', 'flutter.md', 'foundation.md', 'hosting-reliability.md', 'identity-tenancy.md', 'model-lifecycle.md', 'models-observability.md', 'realtime-channels.md', 'security-privacy.md', 'topology-monorepo.md', 'web.md'])
-if (chapters.length !== expectedReferences.size) errors.push(`expected ${expectedReferences.size} normative references, found ${chapters.length}`)
-for (const path of chapters) if (!expectedReferences.delete(basename(path))) errors.push(`unexpected architecture reference ${basename(path)}`)
-for (const missing of expectedReferences) errors.push(`missing architecture reference ${missing}`)
-
-const skillLines = skillBody.split('\n').length
-if (skillLines > 120) errors.push(`SKILL.md exceeds 120 lines (${skillLines})`)
-const routed = new Set([...skillBody.matchAll(/\(references\/architecture\/([^)]+\.md)\)/g)].map(match => match[1]))
-
-const citedSources = new Set()
-for (const path of chapters) {
-  const body = await readFile(path, 'utf8')
-  normativeLines += body.split('\n').length
-  if (!routed.has(basename(path))) errors.push(`${path}: not routed directly from SKILL.md`)
-  for (const match of body.matchAll(/\[([A-Z0-9]+(?:-[A-Z0-9]+)*)\]|<!-- source: ([A-Z0-9]+(?:-[A-Z0-9]+)*) -->/g)) {
-    const id = match[1] ?? match[2]
-    citedSources.add(id)
-    if (!sourceIds.has(id)) errors.push(`${path}: unknown source ${id}`)
-  }
-  for (const [index, line] of body.split('\n').entries()) {
-    const definitions = [...line.matchAll(/\*\*([A-Z]+-[0-9]{3}) —/g)]
-    if (definitions.length && !/\bMUST(?:\s+NOT)?\b/.test(line)) errors.push(`${path}: rule ${definitions[0][1]} must define a MUST or MUST NOT invariant in its canonical line`)
-    if (/\bMUST(?:\s+NOT)?\b/.test(line) && definitions.length !== 1) errors.push(`${path}:${index + 1}: every MUST/MUST NOT must occur in exactly one canonical rule definition`)
-  }
-  for (const block of body.matchAll(/```mermaid\n([\s\S]*?)```/g)) {
-    diagrams += 1
-    const text = block[1].trim()
-    if (!/^(flowchart|sequenceDiagram|stateDiagram-v2)\b/.test(text)) errors.push(`${path}: unsupported Mermaid declaration`)
-    if ((text.match(/\[/g) ?? []).length !== (text.match(/\]/g) ?? []).length) errors.push(`${path}: unbalanced Mermaid brackets`)
-    if (mermaid) try { await mermaid.parse(text) } catch (error) { errors.push(`${path}: Mermaid parser: ${error.message}`) }
-  }
-}
-if (normativeLines > 800) errors.push(`normative references exceed 800 lines (${normativeLines})`)
-if (diagrams < 4) errors.push(`expected at least four decision-useful Mermaid diagrams, found ${diagrams}`)
-
-// criticalSources in foundation-compatibility must mirror every critical:true registry entry —
-// asserted here so the mirror can never drift silently.
-const compatibility = await readJsonYaml(join(references, 'foundation-compatibility.json'))
-const declaredCritical = new Set(compatibility.sourceDrift?.criticalSources ?? [])
-const actualCritical = new Set(registry.sources.filter(source => source.critical).map(source => source.id))
-for (const id of actualCritical) if (!declaredCritical.has(id)) errors.push(`criticalSources mirror missing critical registry source ${id}`)
-for (const id of declaredCritical) if (!actualCritical.has(id)) errors.push(`criticalSources mirror lists non-critical or unknown source ${id}`)
-
-for (const source of registry.sources) {
-  if (!citedSources.has(source.id)) errors.push(`orphan source registry entry ${source.id}`)
-  if (!source.urls?.primary) errors.push(`source ${source.id} has no primary URL`)
-  for (const target of source.affected ?? []) {
-    const [kind, value] = String(target).split(':', 2)
-    if (!['rule', 'ref', 'profile'].includes(kind)) errors.push(`source ${source.id} has invalid affected mapping ${target}`)
-    if (kind === 'rule' && !ruleIds.has(value)) errors.push(`source ${source.id} maps unknown rule ${value}`)
-    if (kind === 'ref' && !await pathExists(join(architectureRoot, `${value}.md`))) errors.push(`source ${source.id} maps unknown reference ${value}`)
-  }
-}
-
-const modeledRules = new Set()
-for (const group of ruleModel.groups ?? []) {
-  for (const required of ['activation', 'verification', 'rationale']) if (!group[required]) errors.push(`rule model group missing ${required}`)
-  for (const rule of group.rules ?? []) {
-    if (modeledRules.has(rule)) errors.push(`rule model duplicates ${rule}`)
-    modeledRules.add(rule)
-    if (!ruleIds.has(rule)) errors.push(`rule model names unknown rule ${rule}`)
-  }
-}
-for (const rule of ruleIds) if (!modeledRules.has(rule)) errors.push(`canonical rule ${rule} has no activation/verification/rationale model`)
-for (const override of ruleModel.overrides ?? []) if (!modeledRules.has(override.rule)) errors.push(`rule model override names unknown rule ${override.rule}`)
-
-const bannedNames = ['golden-architecture.md', 'evidence-manifest.json', 'coverage-matrix.md', 'verification-ledger.md', '23-evidence-comparisons.md', '24-roadmap.md', 'compile-guide.mjs', 'architecture-check.mjs', 'control-catalog.json']
-const allFiles = await listFiles(skillRoot)
-for (const path of allFiles) if (bannedNames.includes(basename(path))) errors.push(`forbidden runtime artifact remains: ${relative(skillRoot, path)}`)
-const runtimeText = (await Promise.all((await listFiles(skillRoot, path => /\.(?:md|json|yaml|yml|mjs)$/.test(path) && !path.includes('/tests/'))).map(path => readFile(path, 'utf8')))).join('\n')
-const historicalNames = ['C' + 'RM', 'S' + 'IM', 'Fl' + 'ue']
-if (new RegExp(`\\b(?:${historicalNames.join('|')})\\b`).test(runtimeText)) errors.push('historical comparison names remain in runtime skill')
-
-const githubSlug = heading => heading.toLowerCase().trim().replace(/<[^>]+>/g, '').replace(/[^\p{L}\p{N}\s-]/gu, '').replace(/\s+/g, '-')
-const headingsFor = body => new Set([...body.matchAll(/^#{1,6}\s+(.+)$/gm)].map(match => githubSlug(match[1])))
-for (const path of await listFiles(skillRoot, path => path.endsWith('.md'))) {
-  const body = await readFile(path, 'utf8')
-  for (const match of body.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
-    const target = match[1]
-    if (/^(https?:|mailto:)/.test(target)) continue
-    const [filePart, anchor] = target.split('#')
-    const targetPath = filePart ? resolve(dirname(path), decodeURIComponent(filePart)) : path
-    if (!await pathExists(targetPath)) { errors.push(`${path}: broken link ${target}`); continue }
-    if (anchor && !headingsFor(await readFile(targetPath, 'utf8')).has(anchor)) errors.push(`${path}: broken anchor ${target}`)
-  }
-  const lines = body.split('\n')
-  for (let index = 0; index < lines.length; index += 1) {
-    if (!lines[index].startsWith('|')) continue
-    const expected = (lines[index].match(/\|/g) ?? []).length
-    let cursor = index + 1
-    while (cursor < lines.length && lines[cursor].startsWith('|')) {
-      const actual = (lines[cursor].match(/\|/g) ?? []).length
-      if (actual !== expected) errors.push(`${path}:${cursor + 1}: malformed Markdown table`)
-      cursor += 1
-    }
-    index = cursor - 1
-  }
-}
-
-if (errors.length) {
-  for (const error of errors) console.error(error)
-  process.exitCode = 1
-} else console.log(`verify-corpus: ${chapters.length} normative references, ${normativeLines} lines, ${ruleIds.size} rules, ${diagrams} Mermaid diagrams, ${sourceIds.size} cited sources, Mermaid mode=${mermaid ? 'formal' : 'structural-fallback'}`)