refactor: replace overloaded surface terminology
This commit is contained in:
Turtle
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/typert/generator/README.md
|
||||
README.md: ac2610620af14a30143e95921273a8c254b50a17
|
||||
README.md: ee71c26141dc56360f4e9e1ae3c7e2add6e3a19b
|
||||
README.zh.md: a1fa777493578533c93db6cd3354b89c8757d837
|
||||
|
||||
@@ -8,7 +8,7 @@ The analyzer can use independent `ts.Program` instances seeded from `tsconfig.ho
|
||||
|
||||
## Analysis Model
|
||||
|
||||
Each face contains package exports, Cordis services and events, explicitly tagged objects and schemas, and a type graph for their reachable declarations. The graph preserves declaration identity, generic parameters and applications, explicit inheritance, conditional and mapped types, import attributes, abstract modifiers, and source JSDoc. Service and `@typert object` surfaces expose public instance members only; constructors, static members, and non-public members are excluded.
|
||||
Each face contains package exports, Cordis services and events, explicitly tagged objects and schemas, and a type graph for their reachable declarations. The graph preserves declaration identity, generic parameters and applications, explicit inheritance, conditional and mapped types, import attributes, abstract modifiers, and source JSDoc. Service and `@typert object` APIs expose public instance members only; constructors, static members, and non-public members are excluded.
|
||||
|
||||
`WorkspaceAnalyzer` defaults to `check` mode and fails on TypeScript syntax or semantic diagnostics, missing reachable public annotations, private cross-package references, and reachable declaration merges that the model cannot retain losslessly. `write` mode inserts checker-derived annotations, rebuilds the program, and returns a clean check-mode model.
|
||||
|
||||
|
||||
@@ -143,7 +143,7 @@ export class CordisCatalogProjector {
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate and project the host model's Cordis surface.
|
||||
* Validate and project the host model's Cordis API.
|
||||
* @returns every validated service and event projected from the host model.
|
||||
*/
|
||||
project(): CordisCatalogModel {
|
||||
@@ -445,7 +445,7 @@ function parseJsDoc(raw: string): ParsedJsDoc {
|
||||
|
||||
function checkParams(
|
||||
where: string,
|
||||
surface: string,
|
||||
apiKind: string,
|
||||
parameters: readonly ParameterModel[],
|
||||
tags: ReadonlyMap<string, string>,
|
||||
isExempt: (parameter: ParameterModel) => boolean,
|
||||
@@ -453,7 +453,7 @@ function checkParams(
|
||||
): void {
|
||||
for (const parameter of parameters) {
|
||||
if (parameter.binding !== 'identifier') {
|
||||
violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`)
|
||||
violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`)
|
||||
continue
|
||||
}
|
||||
if (isExempt(parameter)) continue
|
||||
@@ -579,7 +579,7 @@ function renderRuntimeApi(
|
||||
' *',
|
||||
' * The machine-readable cordis API catalog `cordis_inspect` serves to the',
|
||||
' * model: harness services (summary + public method signatures/JSDoc),',
|
||||
' * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by',
|
||||
' * harness events (mode + signature/JSDoc), and the inherited `ctx` API. Produced by',
|
||||
' * the same AST walk as docs/cordis-catalog, so this data and the rendered',
|
||||
' * docs cannot diverge.',
|
||||
' *',
|
||||
@@ -685,7 +685,7 @@ function renderRuntimeApi(
|
||||
lines.push(
|
||||
']',
|
||||
'',
|
||||
'/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */',
|
||||
'/** The inherited `ctx` API (cordis core + loader/hmr/timer), in curated order. */',
|
||||
'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [',
|
||||
)
|
||||
for (const inherited of inheritedServices) {
|
||||
@@ -775,7 +775,7 @@ const BANNER = [
|
||||
const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
|
||||
|
||||
/**
|
||||
* Render one page's generated `cordis-surface` region: the services mapped to
|
||||
* Render one page's generated Cordis API region: the services mapped to
|
||||
* the page, then the event scopes mapped to it, markers included. Pure and
|
||||
* deterministic given sorted inputs; identical bytes land in both pair sides.
|
||||
* @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.
|
||||
@@ -790,9 +790,9 @@ export function renderPageRegion(page: string, services: ServiceEntry[], events:
|
||||
'',
|
||||
'<a id="cordis-surface"></a>',
|
||||
'',
|
||||
'## Cordis surface',
|
||||
'## Cordis API',
|
||||
'',
|
||||
'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
|
||||
'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
|
||||
'',
|
||||
]
|
||||
for (const s of services) lines.push(...renderService(s, page, policy.linkedTypePages))
|
||||
@@ -816,7 +816,7 @@ export function renderPageRegion(page: string, services: ServiceEntry[], events:
|
||||
export function renderInheritedPage(policy: CordisCatalogPolicy): string {
|
||||
const lines: string[] = [
|
||||
...BANNER,
|
||||
'# Inherited Cordis Surface',
|
||||
'# Inherited Cordis API',
|
||||
'',
|
||||
'The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).',
|
||||
'',
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
/**
|
||||
* Public surface of the Typert analyzer, compiler-independent model, and
|
||||
* Public API of the Typert analyzer, compiler-independent model, and
|
||||
* model-driven artifact emitters. Build wiring lives in the `./tsdown`
|
||||
* subpath.
|
||||
* @module @deepseek-ai/dsh-typert-generator
|
||||
|
||||
@@ -234,7 +234,7 @@ export class TypeGraphRenderer {
|
||||
|
||||
/**
|
||||
* Find the transitive declaration closure referenced by members.
|
||||
* @param memberIds - business-surface member ids.
|
||||
* @param memberIds - business-API member ids.
|
||||
* @returns declarations in graph order, excluding no roots implicitly.
|
||||
*/
|
||||
declarationClosureForMembers(memberIds: readonly string[]): TypeDeclarationModel[] {
|
||||
|
||||
@@ -334,7 +334,7 @@ export class FixService {
|
||||
))).toThrow(/is a binding pattern/)
|
||||
})
|
||||
|
||||
it('ignores private/protected/static members (not the ctx.<key> surface)', () => {
|
||||
it('ignores private/protected/static members (not the ctx.<key> API)', () => {
|
||||
const services = collectServices(makeService(
|
||||
'/** Fixture service. */\nexport class FixService {\n private hidden(id: string): string { return id }\n protected hook(): void {}\n static helper(): void {}\n}',
|
||||
))
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/typert/type-meta/README.md
|
||||
README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
|
||||
README.md: 5bf35dabf80e035ec8eeeef1598873bb4032fa98
|
||||
README.zh.md: 68b690d2143b4420f2e10efceaca0dfc1149d0ff
|
||||
|
||||
@@ -24,7 +24,7 @@ Lookup and Context packages own both sides of their contract: declaration mergin
|
||||
|
||||
## Model Experience
|
||||
|
||||
None, as this protocol package declares application reflection and registers no model surface.
|
||||
None, as this protocol package declares application reflection and registers nothing model-facing.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
|
||||
Reference in New Issue
Block a user