From 4013d772ba36a9d15f1e4fe8427d20b33a40989d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 25 Aug 2026 12:39:36 +0000 Subject: [PATCH] fix(spec): select each skill reference's own module doc block MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit build-skill-references.ts derived every _index.md pointer description from the first doc block anywhere in the source file — a rule about ORDERING, not about descriptions. Whichever declaration happened to sit nearest the top of a .zod.ts donated its comment to a customer-facing page. Converge on the shared findModuleDocBlock() selector that build-docs.ts already uses, imported rather than restated: one selector, two consumers. The column-0 / precedes-first-declaration / documents-no-symbol rule now governs both surfaces, so the two generators stop disagreeing about the same sources. Thirteen pointer rows across seven skills change; skills/** artifacts are regenerated, not hand-edited. The docblock-less fallback to the existing "Exports: ..." line is kept deliberately. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01NDGG54XF5gbTLdQzCtnaVV --- .changeset/skill-refs-module-docblock.md | 33 +++++++++++++++++++ .../spec/scripts/build-skill-references.ts | 29 +++++++++++++--- skills/objectstack-ai/references/_index.md | 2 +- skills/objectstack-api/references/_index.md | 4 +-- .../references/_index.md | 2 +- skills/objectstack-data/references/_index.md | 2 +- skills/objectstack-i18n/references/_index.md | 2 +- .../objectstack-platform/references/_index.md | 8 ++--- skills/objectstack-ui/references/_index.md | 6 ++-- 9 files changed, 70 insertions(+), 18 deletions(-) create mode 100644 .changeset/skill-refs-module-docblock.md diff --git a/.changeset/skill-refs-module-docblock.md b/.changeset/skill-refs-module-docblock.md new file mode 100644 index 0000000000..a0bf6d02f6 --- /dev/null +++ b/.changeset/skill-refs-module-docblock.md @@ -0,0 +1,33 @@ +--- +"@objectstack/spec": patch +--- + +fix(spec): publish each skill reference's own module doc block, not the first doc block in the file + +`build-skill-references.ts` derived every `_index.md` pointer description from +the first doc block anywhere in the source file. That is a rule about ORDERING, +not about descriptions: whichever declaration happened to sit nearest the top of +a `.zod.ts` donated its comment to a customer-facing page, and moving a helper +up a file silently rewrote published text. + +This is the defect the docs-site generator fixed by converging on +`findModuleDocBlock()` — the block must start at column 0, precede the first +declaration, and document no symbol. The skill-references generator was never +converted, so the two generators disagreed about the same sources. It now +imports the same selector rather than restating the rule, and `skills/**` is +loaded whole into customer agent context windows, so it was paying the higher +price for the same defect. + +Thirteen pointer rows across seven skills change. The live victim named on the +issue is `system/translation.zod.ts`, whose `objectstack-i18n` entry opened with +"Shared history sentence for every shape in this file." — the comment on a +private `TRANSLATION_HISTORY` string constant, meaningless to the reader and not +a description of the Translation protocol. Twelve rows in that class now fall +through to the existing `Exports: …` line, and one gains a real module +description (`shared/metadata-types.zod.ts`), which also brings it into +agreement with the docs page for the same file. + +Falling back rather than refusing is deliberate: an export list states a true +fact about the file, where the wrong block asserted a false one about its +subject. Whether a `.zod.ts` on this surface should be required to carry a +module doc block at all is a separate authoring question, left open here. diff --git a/packages/spec/scripts/build-skill-references.ts b/packages/spec/scripts/build-skill-references.ts index 60d37b8c66..29cd355b6e 100644 --- a/packages/spec/scripts/build-skill-references.ts +++ b/packages/spec/scripts/build-skill-references.ts @@ -16,7 +16,7 @@ * 2. Recursively resolves local `import … from` dependencies (so the index * surfaces shared schemas an agent will need to follow) * 3. Writes `skills/{name}/references/_index.md` with pointers + one-line - * descriptions extracted from each file's leading JSDoc comment + * descriptions taken from each file's own MODULE doc block * * Usage: * tsx scripts/build-skill-references.ts # write @@ -25,6 +25,7 @@ import fs from 'fs'; import path from 'path'; +import { findModuleDocBlock } from './lib/file-description'; import { createSink, type Owns } from './lib/generated-output'; // ── Paths ──────────────────────────────────────────────────────────────────── @@ -192,13 +193,31 @@ function resolveAll(entryFiles: string[]): { files: string[]; missing: string[] return { files: shipped.sort(), missing }; } -// ── JSDoc description extractor ────────────────────────────────────────────── +// ── Module description extractor ───────────────────────────────────────────── +/** + * The pointer row's one-line description: the first sentence of the module's + * OWN doc block, or `Exports: …` when the module has none. + * + * WHICH block that is comes from the shared `findModuleDocBlock()` — the same + * selector `build-docs.ts` uses, imported rather than restated so one rule + * serves both surfaces. This generator used to take the first doc block + * anywhere in the file: a rule about ORDERING, not about descriptions, so + * whichever declaration sat nearest the top donated its comment to a + * customer-facing page (`system/translation.zod.ts` published the comment on + * its private `TRANSLATION_HISTORY` const). `check:skill-refs` cannot see that + * — it compares the artifact against the generator, which reproduced the wrong + * block faithfully. + * + * A module with no doc block of its own falls through to the export list + * rather than refusing: that line states a true fact about the file, where the + * wrong block asserted a false one about its subject. + */ function extractDescription(filePath: string): string { const content = fs.readFileSync(filePath, 'utf-8'); - const jsdocMatch = content.match(/\/\*\*\s*\n([\s\S]*?)\*\//); - if (jsdocMatch) { - const lines = jsdocMatch[1] + const moduleBlock = findModuleDocBlock(content); + if (moduleBlock !== null) { + const lines = moduleBlock .split('\n') .map((line) => line.replace(/^\s*\*\s?/, '').trim()) .filter((line) => line && !line.startsWith('@') && !line.startsWith('```')); diff --git a/skills/objectstack-ai/references/_index.md b/skills/objectstack-ai/references/_index.md index a8bbb49ef3..dc43598e14 100644 --- a/skills/objectstack-ai/references/_index.md +++ b/skills/objectstack-ai/references/_index.md @@ -17,7 +17,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/ai/mcp.zod.ts` — Model Context Protocol (MCP) — Reference & Binding Primitives - `node_modules/@objectstack/spec/src/ai/model-registry.zod.ts` — AI Model Registry Protocol - `node_modules/@objectstack/spec/src/ai/skill.zod.ts` — Skill Trigger Condition Schema -- `node_modules/@objectstack/spec/src/ai/tool.zod.ts` — Retired `ToolSchema` keys — the rejection carries the upgrade prescription, +- `node_modules/@objectstack/spec/src/ai/tool.zod.ts` — Exports: ToolSchema - `node_modules/@objectstack/spec/src/ai/usage.zod.ts` — AI Usage Primitives ## Transitive dependencies diff --git a/skills/objectstack-api/references/_index.md b/skills/objectstack-api/references/_index.md index 61861d9ec7..1ff5756163 100644 --- a/skills/objectstack-api/references/_index.md +++ b/skills/objectstack-api/references/_index.md @@ -13,14 +13,14 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/api/batch.zod.ts` — Batch Operations API - `node_modules/@objectstack/spec/src/api/endpoint.zod.ts` — API Mapping Schema - `node_modules/@objectstack/spec/src/api/errors.zod.ts` — Standardized Error Codes Protocol -- `node_modules/@objectstack/spec/src/api/realtime.zod.ts` — Transport Protocol Enum +- `node_modules/@objectstack/spec/src/api/realtime.zod.ts` — Exports: TransportProtocol, RealtimeEventType, SubscriptionEventSchema, SubscriptionSchema, RealtimePresenceSchema - `node_modules/@objectstack/spec/src/api/rest-server.zod.ts` — REST API Server Protocol - `node_modules/@objectstack/spec/src/api/versioning.zod.ts` — API Versioning Protocol - `node_modules/@objectstack/spec/src/api/websocket.zod.ts` — WebSocket Event Protocol ## Transitive dependencies -- `node_modules/@objectstack/spec/src/api/contract.zod.ts` — Machine-readable semantic code (ADR-0112): a `StandardErrorCode` member or +- `node_modules/@objectstack/spec/src/api/contract.zod.ts` — Exports: ApiErrorSchema, BaseResponseSchema, RecordDataSchema, CreateRequestSchema, UpdateRequestSchema - `node_modules/@objectstack/spec/src/api/error-code-ledger.zod.ts` — Error-Code Ledger (ADR-0112 D3). - `node_modules/@objectstack/spec/src/api/realtime-shared.zod.ts` — Realtime Shared Protocol - `node_modules/@objectstack/spec/src/data/data-engine.zod.ts` — Data Engine Protocol diff --git a/skills/objectstack-automation/references/_index.md b/skills/objectstack-automation/references/_index.md index 4fcb2c9460..978ba17d6c 100644 --- a/skills/objectstack-automation/references/_index.md +++ b/skills/objectstack-automation/references/_index.md @@ -9,7 +9,7 @@ from `node_modules` — there is no local copy in the skill bundle. ## Core schemas -- `node_modules/@objectstack/spec/src/automation/approval.zod.ts` — Approval Step Approver Type +- `node_modules/@objectstack/spec/src/automation/approval.zod.ts` — Exports: ApproverType, DEPRECATED_APPROVER_TYPES, NON_AUTHORABLE_APPROVER_TYPES, ORG_MEMBERSHIP_LEVELS, APPROVER_EXPRESSION_ROOTS - `node_modules/@objectstack/spec/src/automation/execution.zod.ts` — Automation Execution Protocol - `node_modules/@objectstack/spec/src/automation/flow.zod.ts` — Flow Node Types — **built-in seed set** (ADR-0018). - `node_modules/@objectstack/spec/src/automation/node-executor.zod.ts` — Node Executor Plugin Protocol — Wait Node Pause/Resume diff --git a/skills/objectstack-data/references/_index.md b/skills/objectstack-data/references/_index.md index f5b8583e77..e17f5bc607 100644 --- a/skills/objectstack-data/references/_index.md +++ b/skills/objectstack-data/references/_index.md @@ -33,7 +33,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/data/driver/turso.zod.ts` — Turso / libSQL Driver Protocol. - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification -- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Capability tokens a script body may request. +- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema - `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/security/rls.zod.ts` — Row-Level Security (RLS) Protocol diff --git a/skills/objectstack-i18n/references/_index.md b/skills/objectstack-i18n/references/_index.md index 107b2c38c5..f7f5f72c5c 100644 --- a/skills/objectstack-i18n/references/_index.md +++ b/skills/objectstack-i18n/references/_index.md @@ -9,7 +9,7 @@ from `node_modules` — there is no local copy in the skill bundle. ## Core schemas -- `node_modules/@objectstack/spec/src/system/translation.zod.ts` — Shared history sentence for every shape in this file. +- `node_modules/@objectstack/spec/src/system/translation.zod.ts` — Exports: LocaleSchema, FieldTranslationSchema, ActionResultDialogTranslationSchema, ObjectTranslationDataSchema, LEGACY_OBJECT_FIRST_KEYS - `node_modules/@objectstack/spec/src/ui/i18n.zod.ts` — Display-label and ARIA-label primitives shared by every `ui/` shape. ## Transitive dependencies diff --git a/skills/objectstack-platform/references/_index.md b/skills/objectstack-platform/references/_index.md index 5aba871b01..d150a469fa 100644 --- a/skills/objectstack-platform/references/_index.md +++ b/skills/objectstack-platform/references/_index.md @@ -12,11 +12,11 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/data/datasource.zod.ts` — Driver Identifier - `node_modules/@objectstack/spec/src/data/seed.zod.ts` — Seed Import Strategy - `node_modules/@objectstack/spec/src/kernel/context.zod.ts` — Runtime Mode Enum -- `node_modules/@objectstack/spec/src/kernel/manifest.zod.ts` — Structured permission grants requested by a plugin (ADR-0025 §3.2). +- `node_modules/@objectstack/spec/src/kernel/manifest.zod.ts` — Exports: PluginPermissionsSchema, ManifestPermissionsSchema, PluginEnginesSchema, PluginRuntimeSchema, PluginPackagingSchema - `node_modules/@objectstack/spec/src/kernel/metadata-plugin.zod.ts` — Metadata Plugin Protocol - `node_modules/@objectstack/spec/src/kernel/plugin-capability.zod.ts` — Plugin Capability Protocol - `node_modules/@objectstack/spec/src/kernel/plugin-loading.zod.ts` — Plugin Loading Protocol -- `node_modules/@objectstack/spec/src/kernel/plugin.zod.ts` — Shared Plugin Types +- `node_modules/@objectstack/spec/src/kernel/plugin.zod.ts` — Exports: PluginContextSchema, CORE_PLUGIN_TYPES, CONSUMER_INSTALLABLE_TYPES, PluginSchema - `node_modules/@objectstack/spec/src/kernel/service-registry.zod.ts` — Service Registry Protocol ## Transitive dependencies @@ -33,14 +33,14 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). - `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification -- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Capability tokens a script body may request. +- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema - `node_modules/@objectstack/spec/src/kernel/cluster.zod.ts` — Cluster Protocol - `node_modules/@objectstack/spec/src/kernel/metadata-customization.zod.ts` — Metadata Customization Layer Protocol - `node_modules/@objectstack/spec/src/kernel/metadata-loader.zod.ts` — Metadata Manager Configuration - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol - `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema -- `node_modules/@objectstack/spec/src/shared/metadata-types.zod.ts` — Exports: MetadataFormatSchema, BaseMetadataRecordSchema +- `node_modules/@objectstack/spec/src/shared/metadata-types.zod.ts` — Supported metadata file formats - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3) - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities - `node_modules/@objectstack/spec/src/system/tenant.zod.ts` — Tenant Schema (Multi-Tenant Architecture) diff --git a/skills/objectstack-ui/references/_index.md b/skills/objectstack-ui/references/_index.md index 73d2513d4c..f4c988bbc0 100644 --- a/skills/objectstack-ui/references/_index.md +++ b/skills/objectstack-ui/references/_index.md @@ -18,7 +18,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/ui/page.zod.ts` — Page Region Schema - `node_modules/@objectstack/spec/src/ui/report.zod.ts` — Report Type Enum - `node_modules/@objectstack/spec/src/ui/view.zod.ts` — HTTP Method Enum & HTTP Request Schema -- `node_modules/@objectstack/spec/src/ui/widget.zod.ts` — Field Widget Props Schema +- `node_modules/@objectstack/spec/src/ui/widget.zod.ts` — Exports: FieldWidgetPropsSchema ## Transitive dependencies @@ -28,7 +28,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). - `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification -- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Capability tokens a script body may request. +- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema - `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/enums.zod.ts` — Exports: SortDirectionEnum, SortItemSchema, MutationEventEnum, IsolationLevelEnum @@ -40,7 +40,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/ui/action-params.zod.ts` — The action DISPATCH contract: what the platform validates on the way in, and - `node_modules/@objectstack/spec/src/ui/bulk-action.zod.ts` — Bulk Action Schemas - `node_modules/@objectstack/spec/src/ui/i18n.zod.ts` — Display-label and ARIA-label primitives shared by every `ui/` shape. -- `node_modules/@objectstack/spec/src/ui/responsive.zod.ts` — Style Map Schema (ADR-0065) +- `node_modules/@objectstack/spec/src/ui/responsive.zod.ts` — Exports: StyleMapSchema, ResponsiveStylesSchema - `node_modules/@objectstack/spec/src/ui/sharing.zod.ts` — Sharing & Embedding Protocol ## How to read these