@voxgig/sdkgen 4.15.0 → 4.17.0

package/src/action/package.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // `package add` / `package list` — the whole-package verbs.
 //
 // See docs/design/sdkgen-packages.md §9.
@@ -78,7 +79,7 @@ const CMD_MAP: any = Object.assign(Object.create(null), {
 // reads them at generate time rather than at add time, installing it last
 // keeps the add log in the order a reader would expect and leaves the model
 // complete before anything reads it.
-const ADD_ORDER = ['target', 'feature', 'docs']
+const ADD_ORDER = ['target', 'feature', 'edition']
 
 
 async function action_package(
@@ -663,7 +664,7 @@ function installedFrom(pkgname: string, actx: ActionContext): Installed[] {
   const found: Installed[] = []
 
   for (const kind of Object.keys(KINDS).sort()) {
-    const items = kit[kind] ?? {}
+    const items = kindCollection({ main: { [KIT]: kit } }, kind)
 
     for (const name of Object.keys(items).sort()) {
       const item = items[name]
@@ -1078,7 +1079,7 @@ async function cmd_package_list(
   const groups: Record<string, any[]> = Object.create(null)
 
   for (const kind of Object.keys(KINDS).sort()) {
-    const items = kit[kind] ?? {}
+    const items = kindCollection({ main: { [KIT]: kit } }, kind)
 
     for (const name of Object.keys(items).sort()) {
       const item = items[name]

package/src/action/resolve.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // Where a `<kind> add <ref>` gets its definition from.
 //
 // One resolver for every KIND of thing an add can install — targets today,
@@ -59,6 +60,9 @@ function lastSegment(ref: string): string {
 
 
 function resolveSource(ref: string, kind: string, ctx$: any): Source {
+  // Registration and copying must resolve a bare resync name identically.
+  const declared = kindCollection(ctx$.model, kind)?.[ref]
+  ref = (isBare(ref) && recordedRef(declared, ref)) || ref
   const root = ctx$.folder
   const fs = ctx$.fs()
 
@@ -275,7 +279,7 @@ function registerInstalled(kind: string, refs: string[], ctx$: any) {
     return
   }
 
-  const items = kit[kind] = kit[kind] ?? {}
+  const items = kindCollection(ctx$.model, kind, true)
 
   for (const ref of refs) {
     let source: Source
@@ -317,7 +321,7 @@ function registerInstalled(kind: string, refs: string[], ctx$: any) {
 function nameConflict(
   kind: string, source: Source, ctx$: any,
 ): { package?: string, base?: string } | undefined {
-  const declared: any = ctx$.model?.main?.[KIT]?.[kind]?.[source.name]
+  const declared: any = kindCollection(ctx$.model, kind)?.[source.name]
 
   if (null == declared || 'object' !== typeof declared) {
     return undefined
@@ -423,6 +427,24 @@ function providesStill(
 }
 
 
+function recordedRef(declared: any, name: string): string | undefined {
+  if (null == declared?.base || '' === declared.base) {
+    return undefined
+  }
+
+  const origname = declared.origname || name
+
+  return Path.join(declared.base, '..', origname) +
+    (origname === name ? '' : '~' + name)
+}
+
+
+// A bare NAME, as opposed to a ref that locates a source.
+function isBare(ref: string): boolean {
+  return !ref.includes('/') && !ref.includes(Path.sep)
+}
+
+
 function normaliseBase(base: string): string {
   return Path.normalize(String(base ?? '')).split(Path.sep).join('/')
 }
@@ -439,6 +461,8 @@ export type {
 
 export {
   resolveSource,
+  recordedRef,
+  isBare,
   registerInstalled,
   nameConflict,
   lastSegment,

package/src/admin/status.ts

@@ -0,0 +1,124 @@
+import Fs from 'node:fs'
+import Path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+function command(cwd: string, bin: string, args: string[]) {
+  return spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: 15000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } })
+}
+function git(cwd: string, args: string[]): string | null {
+  const result = command(cwd, 'git', args)
+  return result.status === 0 ? result.stdout.trim() : null
+}
+function directory(path: string): boolean {
+  return Fs.existsSync(path) && Fs.statSync(path).isDirectory()
+}
+function entries(value: any): [string, any][] {
+  return Object.entries(value || {}).filter(([name]) => !name.includes('$')).sort(([a], [b]) => a.localeCompare(b))
+}
+function workingTree(folder: string) {
+  if (!directory(folder)) return 'missing'
+  const state = git(folder, ['status', '--porcelain=v1', '--untracked-files=normal', '--', '.'])
+  return state === null ? 'not a git repository' : state ? 'modified' : 'clean'
+}
+
+// Read the compiled model and working trees. Never fetch, build, test, or publish.
+export function repositoryStatus(root: string) {
+  root = Path.resolve(root)
+  const sdk = Path.join(root, '.sdk')
+  if (!directory(sdk)) throw new Error('Expected an SDK repository containing .sdk: ' + root)
+  const file = Path.join(sdk, 'model/sdk.json')
+  let model: any, modelError: string | undefined
+  if (Fs.existsSync(file)) {
+    try {
+      model = JSON.parse(Fs.readFileSync(file, 'utf8'))
+      if (!model?.main?.kit) throw new Error('missing main.kit')
+    } catch (err: any) { modelError = 'Invalid compiled model: ' + err.message }
+  }
+  const kit = model?.main?.kit || {}
+  const upstream = git(root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+  const counts = upstream && git(root, ['rev-list', '--left-right', '--count', 'HEAD...@{upstream}'])
+  const [ahead, behind] = counts ? counts.split(/\s+/).map(Number) : [null, null]
+  const packages = ['sdkgen', 'apidef', 'model', 'docgen'].map(name => {
+    const file = Path.join(sdk, 'node_modules/@voxgig', name, 'package.json')
+    try { return { name: '@voxgig/' + name, version: JSON.parse(Fs.readFileSync(file, 'utf8')).version } }
+    catch { return { name: '@voxgig/' + name, version: 'not installed' } }
+  })
+  return {
+    root, name: model?.name || Path.basename(root),
+    repository: {
+      branch: git(root, ['branch', '--show-current']) || 'detached or not initialised',
+      commit: git(root, ['rev-parse', '--short', 'HEAD']), state: workingTree(root), upstream, ahead, behind,
+    },
+    model: { path: file, compiled: !!model && !modelError, error: modelError,
+      generatedAt: Fs.existsSync(file) ? Fs.statSync(file).mtime.toISOString() : null },
+    toolchain: { node: process.version, packages },
+    targets: entries(kit.target).map(([name, target]) => {
+      const folder = Path.resolve(root, target.output?.path || name)
+      const present = directory(folder)
+      return { name, active: target.active !== false, path: folder, present,
+        state: workingTree(folder), readme: Fs.existsSync(Path.join(folder, 'README.md')),
+        version: target.publish?.version || null,
+        publication: target.publish?.registry?.state || 'not recorded',
+      }
+    }),
+    editions: entries(kit.doc?.edition).map(([name, edition]) => ({ name,
+      active: kit.doc?.active !== false && edition.active !== false, kind: edition.kind,
+      path: edition.output?.path || null,
+      present: !!edition.output?.path && Fs.existsSync(Path.resolve(root, edition.output.path)),
+    })),
+  }
+}
+
+function githubStatus(root: string) {
+  const run = (args: string[]) => {
+    const result = command(root, 'gh', args)
+    if (result.status !== 0) throw new Error(result.error?.message || result.stderr.trim() || 'GitHub query failed')
+    return JSON.parse(result.stdout)
+  }
+  const repository = run(['repo', 'view', '--json', 'nameWithOwner,url'])
+  const host = new URL(repository.url).hostname
+  const pages = command(root, 'gh', ['api', '--hostname', host, 'repos/' + repository.nameWithOwner + '/pages'])
+  let site: any
+  try { site = JSON.parse(pages.stdout || '{}') } catch { site = {} }
+  if (pages.status !== 0 && String(site.status) !== '404') throw new Error(pages.error?.message || pages.stderr.trim() || 'Pages query failed')
+  return { repository: repository.nameWithOwner,
+    pages: pages.status === 0 ? { url: site.html_url, status: site.status, buildType: site.build_type } : { status: 'not configured' },
+    runs: run(['run', 'list', '--limit', '5', '--json', 'workflowName,status,conclusion,headBranch,url']),
+  }
+}
+
+export function main(args = process.argv.slice(2)): number {
+  const root = args.shift()
+  if (args.includes('--help') || root === '--help') {
+    console.log('Usage: .sdk/admin/status.sh [--json] [--github]\nRead local repository, SDK, and documentation status. --github also reads Pages and recent CI runs.\nBuild and test results are not inferred from generated files. No commands that change the repository are run.')
+    return 0
+  }
+  if (!root || args.some(arg => !['--json', '--github'].includes(arg))) throw new Error('Usage: status.sh [--json] [--github]')
+  const report: any = repositoryStatus(root)
+  let failed = !!report.model.error
+  if (args.includes('--github')) {
+    try { report.github = githubStatus(report.root) }
+    catch (err: any) { report.github = { error: err.message }; failed = true }
+  }
+  if (args.includes('--json')) console.log(JSON.stringify(report, null, 2))
+  else {
+    console.log('Repository: ' + report.root)
+    console.log('Git: ' + report.repository.branch + ' | ' + report.repository.state + ' | ' + (report.repository.commit || 'no commits'))
+    console.log('Upstream: ' + (report.repository.upstream ? report.repository.upstream + ' | ahead ' + report.repository.ahead + ', behind ' + report.repository.behind + ' (local tracking refs)' : 'not configured'))
+    console.log('Model: ' + (report.model.error || (report.model.compiled ? 'compiled ' + report.model.generatedAt : 'not generated; run npm run generate from .sdk')))
+    console.log('Toolchain: Node ' + report.toolchain.node + '; ' + report.toolchain.packages.map((p: any) => p.name + ' ' + p.version).join('; '))
+    console.log('\nSDKs and tools (publication state comes from the model):')
+    for (const t of report.targets) console.log('  ' + t.name + ' | ' + (t.active ? 'active' : 'inactive') + ' | ' + t.state + ' | version ' + (t.version || 'not recorded') + ' | ' + t.publication + ' | ' + t.path)
+    if (!report.targets.length) console.log('  No targets in the compiled model.')
+    console.log('\nDocumentation:')
+    for (const e of report.editions) console.log('  ' + e.name + ' | ' + (e.active ? 'active' : 'inactive') + ' | ' + (e.present ? 'present' : 'missing') + ' | ' + (e.path || 'no output path'))
+    if (!report.editions.length) console.log('  No editions in the compiled model.')
+    console.log('\nLocal status does not run builds/tests or check registries. Use --github for remote CI and Pages status.')
+    if (report.github) console.log('\nGitHub:\n' + JSON.stringify(report.github, null, 2))
+  }
+  return failed ? 1 : 0
+}
+
+if (require.main === module) {
+  try { process.exitCode = main() } catch (err: any) { console.error(err.message); process.exitCode = 1 }
+}

package/src/cmp/Test.ts

@@ -1,6 +1,6 @@
 
 import {
-  cmp,
+  cmp, File, Content,
 } from 'jostraca'
 
 import { requirePath } from '../utility'
@@ -19,6 +19,18 @@ const Test = cmp(function Test(props: any) {
   const { model, log } = ctx$
   const stdrep = ensureStdrep(ctx$)
 
+  const points = Object.values(model.main.kit.entity || {}).flatMap((entity: any) =>
+    Object.values(entity.op || {}).flatMap((op: any) => op.points || [])) as any[]
+  if (points.some(point => point.contract && JSON.parse(point.contract.json).live)) {
+    const supported = ['ts', 'js'].includes(target.name)
+    File({ name: 'live-coverage.json' }, () => Content(JSON.stringify({
+      version: 1, target: target.name, scenarios: supported ? 'supported' : 'unsupported',
+      points: points.map(point => point.contract?.id || point.method + ' ' + point.orig),
+      ...(!supported ? { reason: 'This target does not yet execute declarative live recipes. Its existing tests do not establish full operation coverage.' } : {}),
+    }, null, 2)))
+    if (!supported) log.warn({ point: 'live-scenarios-unsupported', note: 'Declarative live recipes are not executed by target ' + target.name })
+  }
+
   const Test_sdk = requirePath(ctx$, `./cmp/${target.name}/Test_${target.name}`)
   Test_sdk['Test']({ model, target, stdrep })
 

package/src/helpers/kindCollection.ts

@@ -0,0 +1,11 @@
+import { KIT } from '../types'
+
+// Physical kind names and model namespaces are independent.
+export function kindCollection(model: any, kind: string, create = false): any {
+  const kit = create ? (model.main ??= {})[KIT] ??= {} : model?.main?.[KIT]
+  if (kind === 'edition') {
+    const doc = create ? kit.doc ??= {} : kit?.doc
+    return create ? doc.edition ??= {} : doc?.edition ?? {}
+  }
+  return create ? kit[kind] ??= {} : kit?.[kind] ?? {}
+}

package/src/helpers/modelcheck.ts

@@ -33,6 +33,8 @@
 //      project's own file, not the package's.
 
 import { Aontu } from 'aontu'
+import { createRequire } from 'node:module'
+import Path from 'node:path'
 
 import { schemaFile } from './shipped'
 
@@ -112,8 +114,8 @@ function slashComments(text: string): { line: number, text: string }[] {
 // A FRESH INSTANCE each time: the option call mutates the instance's jsonic,
 // so a cached one would leak its configuration into the bare compile that is
 // deliberately paired with it.
-function strictAontu(): any {
-  const aontu: any = new Aontu()
+function strictAontu(options?: any): any {
+  const aontu: any = new Aontu(options)
   aontu.lang.jsonic.options({ comment: { def: { slash: null, multi: null } } })
   return aontu
 }
@@ -186,7 +188,12 @@ function compileModel(
     includeLine(schemaFile()) + '\n' + src : src
 
   try {
-    const aontu = false === opts?.strict ? new Aontu() : strictAontu()
+    // Resolve package includes from the model being checked, including native
+    // package self-references. The SDK toolchain's dependencies are unrelated.
+    const localRequire = Object.assign(createRequire(Path.resolve(path)), { main: require.main })
+    // Aontu forwards this runtime resolver option to Lang; its public type omits it.
+    const options: any = { require: localRequire }
+    const aontu = false === opts?.strict ? new Aontu(options) : strictAontu(options)
     const model = aontu.generate(text, { path, errs })
 
     return {

package/src/helpers/shipped.ts

@@ -9,9 +9,8 @@
 // installation doing the checking, which is this one.
 //
 // `__dirname` is `dist/helpers` in the shipped package, so the package root is
-// two levels up. npm can only ship files under that root, which is why the
-// canonical `model/` is mirrored into `ts/model/` (the model-mirror guard
-// fails on drift).
+// two levels up. The authoritative schema lives directly in its model/
+// directory, in both a checkout and an installed package.
 
 import Path from 'node:path'
 

package/src/helpers/testPolicy.ts

@@ -1,52 +1,14 @@
-// How strict the generated LIVE tests are.
-//
-// WHY THIS IS A MODEL DECISION
-//
-// The generated direct tests are deliberately lenient in live mode:
-//
-//   if (setup.live) {
-//     // Live mode is lenient: synthetic IDs frequently 4xx.
-//     if (!result.ok || result.status < 200 || result.status >= 300) {
-//       return                       // <-- passes
-//     }
-//   } else {
-//     assert(result.ok === true)
-//     ...
-//   }
-//
-// That is CORRECT for sdkgen's default case — a fleet SDK generated against
-// an arbitrary third-party public API, where synthetic IDs 4xx constantly and
-// list response shapes vary wildly. Asserting there would mean permanent red.
-//
-// It is WRONG for a project that owns the server it tests against, and those
-// projects had no way to say so. Measured on voxgig-solardemo-sdk: the live
-// TypeScript suite reports 186 pass / 0 fail against the local test app —
-// and 184 pass / 2 fail with the server STOPPED. Only the two entity `basic`
-// flows noticed. A green live run said almost nothing.
-//
-// Gaps that announce themselves as a passing test suite are worse than the
-// ones that break a build.
-
 import { KIT } from '../types'
 
-
-// True when live assertions should match the offline ones. Per-target
-// override first, then the SDK-wide default, then false.
-//
-//   main: kit: test: live: strict: true
-//   main: kit: target: go: test: live: strict: true
+// Live requests assert success by default. This never enables fail-fast:
+// independent tests continue and their framework aggregates the failures.
+// An explicit false preserves the legacy exploratory policy for callers
+// migrating a fleet; it must not be confused with full live verification.
 function liveStrict(model: any, target?: string): boolean {
   const perTarget = null == target ? undefined :
     model?.main?.[KIT]?.target?.[target]?.test?.live?.strict
-
-  if (null != perTarget) {
-    return true === perTarget
-  }
-
-  return true === model?.main?.[KIT]?.test?.live?.strict
+  const configured = perTarget ?? model?.main?.[KIT]?.test?.live?.strict
+  return false !== configured
 }
 
-
-export {
-  liveStrict,
-}
+export { liveStrict }