@voxgig/sdkgen 3.0.0 → 3.2.0

package/project/.sdk/src/cmp/ts/Package_ts.ts

@@ -12,6 +12,7 @@ import {
   PUBLISHER,
   PUBLISHER_URL,
   packageVersion,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -29,6 +30,12 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // WHO WROTE THIS PACKAGE. Per target, falling back to the model-wide value
+  // and then to the publisher — so a manifest cannot go on naming Voxgig
+  // while the model names someone else, which is exactly what the hardcoded
+  // constant here did.
+  const author = authorInfo(model, target.name)
+
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
   const only = (kind: string, deps: any) =>
@@ -106,7 +113,7 @@ const Package = cmp(async function Package(props: any) {
       "clean": "rm -rf node_modules yarn.lock package-lock.json dist dist-test",
       "reset": "npm run clean && npm i && npm run build && npm test",
     },
-    author: { name: PUBLISHER, url: PUBLISHER_URL },
+    author,
 
     // TODO: needs to be config
     license: 'MIT',

package/project/.sdk/tm/seneca-provider/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/project/.sdk/tm/seneca-provider/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Seneca Microservices Framework
+
+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/project/.sdk/tm/seneca-provider/Makefile

@@ -0,0 +1,15 @@
+.PHONY: all build test clean reset
+
+all: build test
+
+build:
+	npm run build
+
+test:
+	npm test
+
+clean:
+	rm -rf dist dist-test .tsbuildinfo
+
+reset:
+	npm run reset

package/project/.sdk/tm/seneca-provider/src/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir": "../dist",
+    "rootDir": ".",
+    "tsBuildInfoFile": "../.tsbuildinfo/src.json",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "useDefineForClassFields": false,
+    "declaration": true,
+    "declarationDir": "../dist",
+    "types": ["node"]
+  }
+}

package/project/.sdk/tm/seneca-provider/test/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir": "../dist-test",
+    "rootDir": ".",
+    "tsBuildInfoFile": "../.tsbuildinfo/test.json",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"]
+}

package/project/.sdk/tm/seneca-provider/tsfmt.json

@@ -0,0 +1,3 @@
+{
+  "indentSize": 2
+}

package/src/action/doctor.ts

@@ -4,13 +4,13 @@
 // WHY THIS EXISTS
 //
 // Nothing told a project that its `.sdk/` had drifted. `target add`
-// OVERWRITES the vendored components and template masters, so any hand-edit
-// there is silently reverted on the next run — and any file the scaffold has
-// since stopped shipping just stays, compiling into the output forever. In
-// voxgig-solardemo-sdk two such orphans broke the Go build in a single
-// session: `utility/make_target.go` (replaced upstream by `make_point.go`,
-// leaving a duplicate symbol) and `utility/struct/go.mod` (a nested module
-// that made `utility/struct` unimportable).
+// OVERWRITES the vendored components, the template masters AND the per-target
+// model file, so any hand-edit there is silently reverted on the next run —
+// and any file the scaffold has since stopped shipping just stays, compiling
+// into the output forever. In voxgig-solardemo-sdk two such orphans broke the
+// Go build in a single session: `utility/make_target.go` (replaced upstream by
+// `make_point.go`, leaving a duplicate symbol) and `utility/struct/go.mod` (a
+// nested module that made `utility/struct` unimportable).
 //
 // Every divergence in that repo was found by hand-diffing. Without a check,
 // fixing it once guarantees nothing about next month.
@@ -84,8 +84,9 @@ const ROOT_COMPONENTS: [string, string][] = [
 // What the check found, by category. Categories 1-3 are drift; `additive` is
 // the project's own work and is reported separately, never as a problem.
 type DoctorReport = {
-  // `.sdk/src/cmp/**` that differs from the scaffold. `target add` will
-  // silently revert every one of these.
+  // `.sdk/src/cmp/**`, or a target's own `.sdk/model/target/<t>.aontu`, that
+  // differs from the scaffold. `target add` will silently revert every one of
+  // these.
   forked: string[]
 
   // `.sdk/tm/**` that differs from the scaffold AFTER the same substitution
@@ -252,7 +253,8 @@ function checkTarget(actx: ActionContext, resolved: any, report: DoctorReport) {
   const model = actx.model
   const root = actx.folder
 
-  // The two trees `target add` owns, and the substitution it applies to each.
+  // The two TREES `target add` owns, and the substitution it applies to each.
+  // (It owns one FILE as well — see checkTargetModel, below.)
   //
   //   src/cmp — copied verbatim, so a byte compare is the truth.
   //   tm      — copied through jostraca's template(), with ProjectName.
@@ -329,6 +331,60 @@ function checkTarget(actx: ActionContext, resolved: any, report: DoctorReport) {
       }
     }
   }
+
+  checkTargetModel(actx, resolved, report)
+}
+
+
+// The THIRD thing `target add` writes for a target, and the one nothing
+// compared: `model/target/<t>.aontu` (src/action/target.ts, the Copy with the
+// `'BASE'` replacement).
+//
+// It is not scaffolding trivia. That file carries the target's dependency
+// set, its `phase` gates, `srcfeature`, `feature.trim` / `feature.fullset`
+// and its publish-registry identity — and `target add` OVERWRITES it exactly
+// as it overwrites src/cmp and tm. So a maintainer who fixes a dep version
+// there loses the fix on the next resync with nothing said (the SDK regresses
+// with nobody touching it, which is the failure the "a project decision
+// belongs in the MODEL" rule exists to prevent), and a project whose copy
+// predates a scaffold change carries the old declaration forever while doctor
+// reported the target in sync. Both are the drift this command exists to
+// name; the file was simply in neither tree it walked.
+function checkTargetModel(actx: ActionContext, resolved: any, report: DoctorReport) {
+  const { tname, tfolder, torigname, base } = resolved
+  const fs = actx.fs()
+
+  const scaffold = Path.join(tfolder, 'model', 'target', torigname + '.aontu')
+
+  // No scaffold file means nothing to compare against, which is the ALIASED
+  // target: `target add go~go2` copies go.aontu to model/target/go2.aontu and
+  // docs/how-to/add-a-target.md then tells the project to EDIT it (a second Go
+  // module needs its own module name and deps). doctor resolves a target by
+  // its INSTALLED name — the model records `base`, not the ref it came from —
+  // so the origin is not recoverable here, and reporting that documented edit
+  // as drift on every run is worse than saying nothing.
+  if (!fs.existsSync(scaffold)) {
+    return
+  }
+
+  const project = Path.join(actx.folder, 'model', 'target', tname + '.aontu')
+  const label = 'model/target/' + tname + '.aontu'
+
+  if (!fs.existsSync(project)) {
+    report.missing.push(label)
+    return
+  }
+
+  // The substitution `target add` applied on the way in: jostraca's template()
+  // against the model (so `module: name: '$$name$$'` arrives as the project
+  // slug) plus the `'BASE'` replacement recording where the scaffold was.
+  //
+  // NOT templateReplacements() — that is the tm/ tree's map. The two writers
+  // pass different maps, so doctor has to as well, or every csharp/swift/ts
+  // project reads as forked on the `base:` line alone.
+  if (differs(fs, scaffold, project, actx.model, { "'BASE'": "'" + base + "'" })) {
+    report.forked.push(label)
+  }
 }
 
 
@@ -384,8 +440,17 @@ function differs(
   }
 
   const src = fs.readFileSync(scaffoldPath, 'utf8')
-  const expected = 0 === Object.keys(replace).length ? src :
-    template(src, model, { replace })
+
+  // template() runs even when there is nothing to REPLACE, because jostraca's
+  // Copy always interpolates `$$ref$$` against the model as well — the replace
+  // map is an extra, not the whole substitution. Skipping it for the src/cmp
+  // tree (whose Copy passes no replace map) meant the three Config fragments
+  // that carry `$$const.Name$$` / `$$main.kit.info.servers.0.url$$` arrived
+  // substituted and compared as bytes: every project with ts, js or dart
+  // reported `src/cmp/<t>/fragment/Config.fragment.<ext>` as FORKED straight
+  // out of `target add`, which is precisely the noise this function exists to
+  // remove. With no `$$` refs and no replace keys, template() is the identity.
+  const expected = template(src, model, { replace })
 
   return expected !== fs.readFileSync(projectPath, 'utf8')
 }

package/src/cmp/ExternalTarget.ts

@@ -0,0 +1,125 @@
+// The Root for a target that generates OUTSIDE the SDK repo
+// (`main: kit: target: <t>: output: path`).
+//
+// WHY THIS EXISTS, rather than a folder name
+//
+// A target's files normally land in `<sdk-repo>/<target>/`, which the
+// consumer's own `Root.ts` arranges with `Folder({ name: target.name })`.
+// Two things stop that reaching a sibling repo:
+//
+//   - jostraca REFUSES a `..` segment in a Folder name (FileHandler.validName
+//     throws). Escaping the output root through a folder name is not an
+//     oversight to work around; it is the guard that keeps generation inside
+//     the tree it was pointed at.
+//   - the output root is `jopts.folder`, per generate() CALL. So writing
+//     somewhere else means another call, not another folder.
+//
+// So an out-of-tree target gets its own generate() pass, rooted at its
+// output path, with this as the Root. It renders ONE target and nothing
+// else: the consumer Root also emits the SDK repo's own furniture (its
+// README, AGENTS.md, the build scaffold), and none of that belongs in a
+// separate package's repo.
+//
+// No Folder wraps the target here — the destination IS the package, so its
+// files go at the root of the output path.
+//
+// The phase gate mirrors the consumer Root exactly, so `output.path` is not
+// a consumer-target feature: point a language target at another repo and it
+// generates there the same way it would in-tree.
+
+import { cmp, each, names } from 'jostraca'
+
+import { Project } from 'jostraca'
+
+import { KIT } from '@voxgig/apidef'
+
+import { Main } from './Main'
+import { Entity } from './Entity'
+import { Feature } from './Feature'
+import { Readme } from './Readme'
+import { Test } from './Test'
+import { AgentGuide } from './AgentGuide'
+
+
+const ExternalTarget = cmp(function ExternalTarget(props: any) {
+  const { model, target, cmpfolder, sdkrelpath } = props
+  const ctx$ = props.ctx$
+
+  ctx$.model = model
+
+  // Components live in the PROJECT, not in the repo being written to. This
+  // pass has retargeted jostraca's output folder, which is what requirePath
+  // otherwise resolves against — see utility.resolvePath.
+  ctx$.cmpfolder = cmpfolder
+
+  // The path from the destination back to the SDK project, for a target whose
+  // output sits beside the SDK in a known layout.
+  ctx$.sdkrelpath = sdkrelpath
+
+  // The same model preamble the consumer's Root.ts performs before it renders
+  // anything: the case-variant name constants (`Name`, `NAME`, ...) and the
+  // ProjectName replacement map that every template substitution reads.
+  //
+  // Done HERE rather than relied upon, because this pass gets the model the
+  // in-tree pass never touched — Root mutates the filtered copy it is handed,
+  // not this one — and because an SDK project with only out-of-tree targets
+  // must generate the same way as one with both.
+  model.const = model.const || { name: model.name }
+  names(model.const, model.name)
+  if (null == model.const.year) {
+    model.const.year = new Date().getFullYear()
+  }
+  names(model, model.name)
+
+  ctx$.stdrep = ctx$.stdrep || {}
+  names(ctx$.stdrep, model.Name, 'Project' + 'Name')
+
+  const entity = model.main[KIT].entity || {}
+  const feature = model.main[KIT].feature || {}
+
+  // Defaults are inclusive: a phase runs unless the target's model turns it
+  // off. Consumer targets (go-cli, go-mcp, py-data, seneca-provider) switch
+  // every phase off and emit everything from Main.
+  const phase = target.phase || {}
+  const phaseActive = (name: string): boolean =>
+    false !== (phase[name] && phase[name].active)
+
+  Project({}, () => {
+    names(target, target.name)
+
+    if (phaseActive('entity')) {
+      each(entity, (entity: any) => {
+        names(entity, entity.name)
+        Entity({ target, entity })
+      })
+    }
+
+    if (phaseActive('feature')) {
+      each(feature)
+        .filter((feature: any) => feature.active)
+        .map((feature: any) => {
+          names(feature, feature.name)
+          Feature({ target, feature })
+        })
+    }
+
+    Main({ target })
+
+    if (phaseActive('readme')) {
+      Readme({ target })
+    }
+
+    if (phaseActive('agentguide')) {
+      AgentGuide({ target })
+    }
+
+    if (phaseActive('test')) {
+      Test({ target })
+    }
+  })
+})
+
+
+export {
+  ExternalTarget,
+}

package/src/helpers/packageMeta.ts

@@ -14,6 +14,8 @@
 // Every value here is derived from the resolved model (model.name, model.origin,
 // main.kit.info.title) — no new inputs required.
 
+import { each } from 'jostraca'
+
 import { KIT, nom } from '@voxgig/apidef'
 
 const PUBLISHER = 'Voxgig'
@@ -348,6 +350,65 @@ function keywords(model: any): string[] {
   return ['voxgig', 'sdk', 'generated-sdk', 'openapi', 'api-client', model.name]
 }
 
+
+// WHO WROTE THE PACKAGE — `main: kit: author` / `main: kit: contributor`.
+//
+// Attribution cannot be derived: it is not a function of the slug, the repo or
+// the API. And because generated output is OVERWRITTEN, a name hand-edited
+// into a manifest is deleted by the next regeneration — silently, because no
+// build step can tell that a person is missing. The seneca-provider target
+// dropped a hand-written provider's author and both its named contributors
+// exactly that way. So attribution is declared in the model and read here.
+//
+// An unset author is the PUBLISHER, which is what every generated SDK manifest
+// has always carried (Package_ts hardcoded it); a project that has never
+// thought about authorship keeps the previous behaviour.
+//
+// PER TARGET, falling back to the model-wide value. One model can produce
+// packages with different authors: the SDK is a generated artefact of the
+// publisher, while a Seneca provider is an independently released package with
+// its own human maintainers. A single model-wide name cannot be right for
+// both — and it was not: the solardemo model named a person, the target that
+// read it credited them, and the SDK's own manifest went on saying Voxgig
+// because it read nothing at all.
+//
+//   main: kit: author: { ... }                    # every package from this model
+//   main: kit: target: ts: author: { ... }        # ...except this one
+function authorInfo(model: any, target?: string): { name: string, url: string } {
+  const perTarget = null == target ? null :
+    model?.main?.[KIT]?.target?.[target]?.author
+
+  const declared = (null != perTarget && '' !== (perTarget.name || '')) ?
+    perTarget : (model?.main?.[KIT]?.author || {})
+
+  const name = null != declared.name && '' !== declared.name ?
+    String(declared.name) : PUBLISHER
+
+  // A declared author with no url gets none — inventing PUBLISHER_URL for a
+  // named human would credit them to Voxgig's homepage.
+  const url = null != declared.url && '' !== declared.url ? String(declared.url) :
+    (PUBLISHER === name ? PUBLISHER_URL : '')
+
+  return { name, url }
+}
+
+
+// Contributors, in sorted-key order so the manifest is byte-stable. `each`
+// rather than Object.keys: the model is an aontu map and carries metadata
+// keys alongside its entries.
+//
+// An entry with no name is DROPPED rather than rendered as `{}` — the schema
+// makes `name` required, but a partially-unified model can still reach here
+// during a dry run.
+function contributorList(model: any): { name: string, url: string }[] {
+  return each(model?.main?.[KIT]?.contributor || {})
+    .filter((c: any) => null != c && null != c.name && '' !== c.name)
+    .map((c: any) => ({
+      name: String(c.name),
+      url: null != c.url && '' !== c.url ? String(c.url) : '',
+    }))
+}
+
 // A VALID uppercase env-var token: 'unsolicited-advice' -> 'UNSOLICITED_ADVICE'.
 //
 // THE ONLY WAY to build an env-var name segment. There used to be three
@@ -387,6 +448,8 @@ export {
   pkgDescription,
   nonAffiliation,
   keywords,
+  authorInfo,
+  contributorList,
   envName,
   envToken,
   goModule,