Skip to content

fix(spec): 基线编码统一为裸字符,写盘端与文件共用一个序列化器 (#5990) #6096

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 1 commit into from
Aug 7, 2026
+280 −153
Merged

fix(spec): 基线编码统一为裸字符,写盘端与文件共用一个序列化器 (#5990) #6096

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 137 additions & 137 deletions packages/spec/docs-import-surface.baseline.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,141 +1,141 @@
{
"_comment": "Accepted gaps between the reference docs' import examples and the real export surface of @objectstack/spec (#4570): a documented JSON Schema whose entry point exports no matching type alias (\"no type export\") or no matching schema const (\"no schema const export\"). The name is omitted from the generated import line \u2014 the docs never advertise an import that cannot compile \u2014 and listed here so the omission is countable instead of silent. Shrink-only ratchet: a NEW gap fails check:docs (fix it by adding `export type X = z.infer<typeof XSchema>;` next to the schema and regenerating api-surface.json, or by retiring the schema together with its alias), and a stale entry fails until its line is deleted. Growing this list is a maintainer decision that shows up as this file in the diff. Regenerate with: tsx scripts/build-docs.ts --update-import-baseline (after gen:schema).",
"_comment": "Accepted gaps between the reference docs' import examples and the real export surface of @objectstack/spec (#4570): a documented JSON Schema whose entry point exports no matching type alias (\"no type export\") or no matching schema const (\"no schema const export\"). The name is omitted from the generated import line — the docs never advertise an import that cannot compile — and listed here so the omission is countable instead of silent. Shrink-only ratchet: a NEW gap fails check:docs (fix it by adding `export type X = z.infer<typeof XSchema>;` next to the schema and regenerating api-surface/, or by retiring the schema together with its alias), and a stale entry fails until its line is deleted. Growing this list is a maintainer decision that shows up as this file in the diff. Regenerate with: tsx scripts/build-docs.ts --update-import-baseline (after gen:schema).",
"entries": [
"ai/AIModelConfig \u2014 no type export",
"ai/CodeContent \u2014 no type export",
"ai/FileContent \u2014 no type export",
"ai/ImageContent \u2014 no type export",
"ai/TextContent \u2014 no type export",
"api/AnalyticsResultResponse \u2014 no type export",
"api/ApiMapping \u2014 no type export",
"api/Discovery \u2014 no type export",
"api/GetAnalyticsMetaRequest \u2014 no type export",
"api/HttpFindQueryParams \u2014 no type export",
"api/MetadataBulkUnregisterRequest \u2014 no type export",
"api/MetadataExportRequest \u2014 no type export",
"api/MetadataImportRequest \u2014 no type export",
"api/MetadataOverlaySaveRequest \u2014 no type export",
"api/MetadataQueryRequest \u2014 no type export",
"api/MetadataValidateRequest \u2014 no type export",
"api/SubscriptionEvent \u2014 no type export",
"automation/ApproverType \u2014 no type export",
"automation/FlowNodeAction \u2014 no type export",
"automation/FlowVariable \u2014 no type export",
"automation/GuardRef \u2014 no type export",
"automation/StateMachine \u2014 no type export",
"automation/StateNode \u2014 no type export",
"data/AddressValue \u2014 no type export",
"data/AggregationFunction \u2014 no type export",
"data/AggregationMetricType \u2014 no type export",
"data/CalendarDateValue \u2014 no type export",
"data/ClockTimeValue \u2014 no type export",
"data/ContextTokenPlaceholder \u2014 no type export",
"data/DataEngineAggregateRequest \u2014 no type export",
"data/DataEngineCountRequest \u2014 no type export",
"data/DataEngineDeleteRequest \u2014 no type export",
"data/DataEngineExecuteRequest \u2014 no type export",
"data/DataEngineFindOneRequest \u2014 no type export",
"data/DataEngineFindRequest \u2014 no type export",
"data/DataEngineInsertRequest \u2014 no type export",
"data/DataEngineUpdateRequest \u2014 no type export",
"data/DataEngineVectorFindRequest \u2014 no type export",
"data/DateGranularity \u2014 no type export",
"data/DateMacroPlaceholder \u2014 no type export",
"data/DimensionType \u2014 no type export",
"data/DriverSslToggle \u2014 no type export",
"data/DriverType \u2014 no type export",
"data/EqualityOperator \u2014 no type export",
"data/FileLikeValue \u2014 no type export",
"data/FileReferenceIdValue \u2014 no type export",
"data/FileValue \u2014 no type export",
"data/HookEvent \u2014 no type export",
"data/Index \u2014 no type export",
"data/InstantValue \u2014 no type export",
"data/LocationValue \u2014 no type export",
"data/Object \u2014 no type export",
"data/ObjectOwnershipEnum \u2014 no type export",
"data/Query \u2014 no type export",
"data/ReferenceIdValue \u2014 no type export",
"data/SeedMode \u2014 no type export",
"data/SetOperator \u2014 no type export",
"data/SpecialOperator \u2014 no type export",
"data/StringOperator \u2014 no type export",
"data/TimeUpdateInterval \u2014 no type export",
"data/TransformType \u2014 no type export",
"integration/ConnectorAction \u2014 no type export",
"integration/ConnectorInstanceAPIKeyAuth \u2014 no type export",
"integration/ConnectorInstanceBasicAuth \u2014 no type export",
"integration/ConnectorInstanceBearerAuth \u2014 no type export",
"integration/ConnectorInstanceNoAuth \u2014 no type export",
"integration/ConnectorTrigger \u2014 no type export",
"kernel/DependencyStatusEnum \u2014 no type export",
"kernel/EventMetadata \u2014 no type export",
"kernel/Manifest \u2014 no type export",
"kernel/MetadataCategoryEnum \u2014 no type export",
"kernel/PackageStatusEnum \u2014 no type export",
"kernel/Plugin \u2014 no type export",
"qa/TestActionType \u2014 no type export",
"qa/TestAssertionType \u2014 no type export",
"qa/TestContext \u2014 no type export",
"security/OWDModel \u2014 no type export",
"security/ShareRecipientType \u2014 no type export",
"security/SharingLevel \u2014 no type export",
"security/SharingRuleType \u2014 no type export",
"shared/IsolationLevelEnum \u2014 no type export",
"shared/MutationEventEnum \u2014 no type export",
"shared/SortDirectionEnum \u2014 no type export",
"studio/PanelLocation \u2014 no type export",
"system/AddFieldOperation \u2014 no type export",
"system/CreateObjectOperation \u2014 no type export",
"system/DeleteObjectOperation \u2014 no type export",
"system/DeployStatusEnum \u2014 no type export",
"system/ExecuteSqlOperation \u2014 no type export",
"system/KernelServiceMap \u2014 no type export",
"system/Locale \u2014 no type export",
"system/MetadataState \u2014 no type export",
"system/MigrationDependency \u2014 no type export",
"system/ModifyFieldOperation \u2014 no type export",
"system/RemoveFieldOperation \u2014 no type export",
"system/RenameObjectOperation \u2014 no type export",
"system/ServiceConfig \u2014 no type export",
"system/ServiceCriticality \u2014 no type export",
"system/ServiceStatus \u2014 no type export",
"ui/AIChatWindowProps \u2014 no type export",
"ui/ActionType \u2014 no type export",
"ui/BreakpointColumnMap \u2014 no type export",
"ui/BreakpointOrderMap \u2014 no type export",
"ui/CalendarConfig \u2014 no type export",
"ui/DerivedMeasureOp \u2014 no type export",
"ui/ElementButtonProps \u2014 no type export",
"ui/ElementFilterProps \u2014 no type export",
"ui/ElementFormProps \u2014 no type export",
"ui/ElementImageProps \u2014 no type export",
"ui/ElementMetadataViewerProps \u2014 no type export",
"ui/ElementNumberProps \u2014 no type export",
"ui/ElementRecordPickerProps \u2014 no type export",
"ui/ElementTextInputProps \u2014 no type export",
"ui/ElementTextProps \u2014 no type export",
"ui/GanttConfig \u2014 no type export",
"ui/GanttQuickFilter \u2014 no type export",
"ui/GroupingField \u2014 no type export",
"ui/KanbanConfig \u2014 no type export",
"ui/NavigationMode \u2014 no type export",
"ui/ObjectListView \u2014 no type export",
"ui/ObjectUserFilters \u2014 no type export",
"ui/PageAccordionProps \u2014 no type export",
"ui/PageCardProps \u2014 no type export",
"ui/PageComponentType \u2014 no type export",
"ui/PageHeaderProps \u2014 no type export",
"ui/PageTabsProps \u2014 no type export",
"ui/RecordActivityProps \u2014 no type export",
"ui/RecordChatterProps \u2014 no type export",
"ui/RecordDetailsProps \u2014 no type export",
"ui/RecordHighlightsField \u2014 no type export",
"ui/RecordHighlightsProps \u2014 no type export",
"ui/RecordPathProps \u2014 no type export",
"ui/RecordRelatedListProps \u2014 no type export",
"ui/ReportType \u2014 no type export",
"ui/TreeConfig \u2014 no type export",
"ui/ViewItemName \u2014 no type export"
"ai/AIModelConfig — no type export",
"ai/CodeContent — no type export",
"ai/FileContent — no type export",
"ai/ImageContent — no type export",
"ai/TextContent — no type export",
"api/AnalyticsResultResponse — no type export",
"api/ApiMapping — no type export",
"api/Discovery — no type export",
"api/GetAnalyticsMetaRequest — no type export",
"api/HttpFindQueryParams — no type export",
"api/MetadataBulkUnregisterRequest — no type export",
"api/MetadataExportRequest — no type export",
"api/MetadataImportRequest — no type export",
"api/MetadataOverlaySaveRequest — no type export",
"api/MetadataQueryRequest — no type export",
"api/MetadataValidateRequest — no type export",
"api/SubscriptionEvent — no type export",
"automation/ApproverType — no type export",
"automation/FlowNodeAction — no type export",
"automation/FlowVariable — no type export",
"automation/GuardRef — no type export",
"automation/StateMachine — no type export",
"automation/StateNode — no type export",
"data/AddressValue — no type export",
"data/AggregationFunction — no type export",
"data/AggregationMetricType — no type export",
"data/CalendarDateValue — no type export",
"data/ClockTimeValue — no type export",
"data/ContextTokenPlaceholder — no type export",
"data/DataEngineAggregateRequest — no type export",
"data/DataEngineCountRequest — no type export",
"data/DataEngineDeleteRequest — no type export",
"data/DataEngineExecuteRequest — no type export",
"data/DataEngineFindOneRequest — no type export",
"data/DataEngineFindRequest — no type export",
"data/DataEngineInsertRequest — no type export",
"data/DataEngineUpdateRequest — no type export",
"data/DataEngineVectorFindRequest — no type export",
"data/DateGranularity — no type export",
"data/DateMacroPlaceholder — no type export",
"data/DimensionType — no type export",
"data/DriverSslToggle — no type export",
"data/DriverType — no type export",
"data/EqualityOperator — no type export",
"data/FileLikeValue — no type export",
"data/FileReferenceIdValue — no type export",
"data/FileValue — no type export",
"data/HookEvent — no type export",
"data/Index — no type export",
"data/InstantValue — no type export",
"data/LocationValue — no type export",
"data/Object — no type export",
"data/ObjectOwnershipEnum — no type export",
"data/Query — no type export",
"data/ReferenceIdValue — no type export",
"data/SeedMode — no type export",
"data/SetOperator — no type export",
"data/SpecialOperator — no type export",
"data/StringOperator — no type export",
"data/TimeUpdateInterval — no type export",
"data/TransformType — no type export",
"integration/ConnectorAction — no type export",
"integration/ConnectorInstanceAPIKeyAuth — no type export",
"integration/ConnectorInstanceBasicAuth — no type export",
"integration/ConnectorInstanceBearerAuth — no type export",
"integration/ConnectorInstanceNoAuth — no type export",
"integration/ConnectorTrigger — no type export",
"kernel/DependencyStatusEnum — no type export",
"kernel/EventMetadata — no type export",
"kernel/Manifest — no type export",
"kernel/MetadataCategoryEnum — no type export",
"kernel/PackageStatusEnum — no type export",
"kernel/Plugin — no type export",
"qa/TestActionType — no type export",
"qa/TestAssertionType — no type export",
"qa/TestContext — no type export",
"security/OWDModel — no type export",
"security/ShareRecipientType — no type export",
"security/SharingLevel — no type export",
"security/SharingRuleType — no type export",
"shared/IsolationLevelEnum — no type export",
"shared/MutationEventEnum — no type export",
"shared/SortDirectionEnum — no type export",
"studio/PanelLocation — no type export",
"system/AddFieldOperation — no type export",
"system/CreateObjectOperation — no type export",
"system/DeleteObjectOperation — no type export",
"system/DeployStatusEnum — no type export",
"system/ExecuteSqlOperation — no type export",
"system/KernelServiceMap — no type export",
"system/Locale — no type export",
"system/MetadataState — no type export",
"system/MigrationDependency — no type export",
"system/ModifyFieldOperation — no type export",
"system/RemoveFieldOperation — no type export",
"system/RenameObjectOperation — no type export",
"system/ServiceConfig — no type export",
"system/ServiceCriticality — no type export",
"system/ServiceStatus — no type export",
"ui/AIChatWindowProps — no type export",
"ui/ActionType — no type export",
"ui/BreakpointColumnMap — no type export",
"ui/BreakpointOrderMap — no type export",
"ui/CalendarConfig — no type export",
"ui/DerivedMeasureOp — no type export",
"ui/ElementButtonProps — no type export",
"ui/ElementFilterProps — no type export",
"ui/ElementFormProps — no type export",
"ui/ElementImageProps — no type export",
"ui/ElementMetadataViewerProps — no type export",
"ui/ElementNumberProps — no type export",
"ui/ElementRecordPickerProps — no type export",
"ui/ElementTextInputProps — no type export",
"ui/ElementTextProps — no type export",
"ui/GanttConfig — no type export",
"ui/GanttQuickFilter — no type export",
"ui/GroupingField — no type export",
"ui/KanbanConfig — no type export",
"ui/NavigationMode — no type export",
"ui/ObjectListView — no type export",
"ui/ObjectUserFilters — no type export",
"ui/PageAccordionProps — no type export",
"ui/PageCardProps — no type export",
"ui/PageComponentType — no type export",
"ui/PageHeaderProps — no type export",
"ui/PageTabsProps — no type export",
"ui/RecordActivityProps — no type export",
"ui/RecordChatterProps — no type export",
"ui/RecordDetailsProps — no type export",
"ui/RecordHighlightsField — no type export",
"ui/RecordHighlightsProps — no type export",
"ui/RecordPathProps — no type export",
"ui/RecordRelatedListProps — no type export",
"ui/ReportType — no type export",
"ui/TreeConfig — no type export",
"ui/ViewItemName — no type export"
]
}
22 changes: 6 additions & 16 deletions packages/spec/scripts/build-docs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ import {
evaluateBaseline,
loadEntrySurfaces,
resolveImports,
serializeImportBaseline,
type CategorySurface,
} from './lib/docs-import-surface';
import { escapeMdxDescription } from './lib/escape-mdx';
Expand Down Expand Up @@ -249,18 +250,6 @@ const ENTRY_SURFACES: ReadonlyMap<string, CategorySurface> = loadEntrySurfaces(
/** Every unresolvable import name this run met, one stable line each. */
const importGaps = new Set<string>();

const IMPORT_BASELINE_COMMENT =
'Accepted gaps between the reference docs\' import examples and the real export surface of ' +
'@objectstack/spec (#4570): a documented JSON Schema whose entry point exports no matching type ' +
'alias ("no type export") or no matching schema const ("no schema const export"). The name is ' +
'omitted from the generated import line — the docs never advertise an import that cannot compile ' +
'— and listed here so the omission is countable instead of silent. Shrink-only ratchet: a NEW gap ' +
'fails check:docs (fix it by adding `export type X = z.infer<typeof XSchema>;` next to the schema ' +
'and regenerating api-surface/, or by retiring the schema together with its alias), and a ' +
'stale entry fails until its line is deleted. Growing this list is a maintainer decision that ' +
'shows up as this file in the diff. Regenerate with: ' +
'tsx scripts/build-docs.ts --update-import-baseline (after gen:schema).';

/**
* Resolve a schema name to its page, AS SEEN FROM the category being rendered.
* Returns null when the schema isn't one we generate a page for, or when the
Expand Down Expand Up @@ -943,10 +932,11 @@ if (managedCount > 0) {
const gaps = [...importGaps].sort();

if (UPDATE_IMPORT_BASELINE) {
fs.writeFileSync(
IMPORT_BASELINE_PATH,
JSON.stringify({ _comment: IMPORT_BASELINE_COMMENT, entries: gaps }, null, 2) + '\n',
);
// Serialized through the lib, never inline: the same function is what the
// round-trip pin in `docs-import-surface.test.ts` re-serializes the
// committed file with, so this writer and that file cannot drift into two
// encodings again (#5990).
fs.writeFileSync(IMPORT_BASELINE_PATH, serializeImportBaseline(gaps));
console.log(`Wrote ${gaps.length} import-surface gap(s) to ${path.relative(REPO_ROOT, IMPORT_BASELINE_PATH)} — review the diff before committing.`);
} else {
const baseline: { entries?: string[] } = fs.existsSync(IMPORT_BASELINE_PATH)
Expand Down
Loading
Loading