iframe-proxy | Sunbelt Computer Software

History

234 lines (209 loc) · 6.75 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

/**

* Reads generated `.d.mts` files and writes compact `api-surface.md` snapshots per package.

* Strips region/source-map directives, non-deprecated block comments, import-only lines,

* and excess blank lines. Blocks mentioning `@deprecated` are kept verbatim.

* @remarks

* Run: `node scripts/generate-api-surface.js` — or via root `postbuild` after `pnpm build`.

* Output is formatted with Oxfmt using the repo root `oxfmt.config.ts` so it matches `pnpm format`.

import fs from 'node:fs';

import path from 'node:path';

import process from 'node:process';

import { format } from 'oxfmt';

import oxfmtConfig from '../oxfmt.config.ts';

const ROOT = path.resolve(import.meta.dirname, '..');

const packages = [

{

// Self-contained DTS from the single-entry api-surface build (see tsdown.config.ts).

// The published `dist/src/index.d.mts` only re-exports names from a shared chunk,

// so it would not capture signatures for `defineAddon`, `officialAddons`, etc.

dts: 'packages/sv/dts-api-surface/index/index.d.mts',

out: 'packages/sv/api-surface.md'

{

dts: 'packages/sv/dts-api-surface/testing/testing.d.mts',

out: 'packages/sv/api-surface-testing.md'

{

dts: 'packages/sv-utils/dist/index.d.mts',

out: 'packages/sv-utils/api-surface.md'

}

];

/**

* Remove `//#region` / `//#endregion` lines emitted by the DTS bundler.

* @param {string} source

* @returns {string}

function stripRegionDirectives(source) {

return source

.split('\n')

.filter((line) => !/^\s*\/\/#(region|endregion)\b/.test(line))

.join('\n');

}

/**

* Remove `//# sourceMappingURL=...` lines from declaration emit.

* @param {string} source

* @returns {string}

function stripSourceMappingUrl(source) {

return source

.split('\n')

.filter((line) => !/^\s*\/\/#\s*sourceMappingURL=/.test(line))

.join('\n');

}

/**

* Remove slash-star-star block comments unless they contain `@deprecated` (full block kept).

* @param {string} source

* @returns {string}

function stripJsDoc(source) {

return source.replace(/\/\*\*[\s\S]*?\*\//g, (match) => {

if (/@deprecated\b/.test(match)) {

return match;

}

return '';

});

}

/**

* Drop top-level `import …` lines (types-only noise in the snapshot).

* @param {string} source

* @returns {string}

function stripImportLines(source) {

return source

.split('\n')

.filter((line) => !line.match(/^import\s/))

.join('\n');

}

/**

* Collapse three or more consecutive newlines to two.

* @param {string} source

* @returns {string}

function collapseBlankLines(source) {

return source.replace(/\n{3,}/g, '\n\n');

}

/**

* Apply all cleaning steps to declaration text.

* @param {string} source

* @returns {string}

function clean(source) {

let result = stripRegionDirectives(source);

result = stripSourceMappingUrl(result);

result = stripJsDoc(result);

result = stripImportLines(result);

result = collapseBlankLines(result);

return result.trim() + '\n';

}

/**

* Format a file with repo Oxfmt options.

* @param {string} absPath absolute path to the markdown file

* @returns {Promise<void>}

async function formatWithOxfmt(absPath) {

const raw = fs.readFileSync(absPath, 'utf8');

const formatted = (await format(absPath, raw, oxfmtConfig)).code;

fs.writeFileSync(absPath, formatted, 'utf8');

}

/**

* Collect names marked `@deprecated` in chunk files imported by the entry .d.mts.

* Returns a Set of exported names whose declarations carry `@deprecated`.

* @param {string} entrySource

* @param {string} entryDir

* @returns {Set<string>}

function collectDeprecatedFromChunks(entrySource, entryDir) {

/** @type {Set<string>} */

const deprecated = new Set();

// match: import { A as Foo, B as Bar } from "../chunk.mjs";

const importRe = /^import\s+\{([^}]+)\}\s+from\s+"([^"]+)"/gm;

let m;

while ((m = importRe.exec(entrySource))) {

const specifiers = m[1];

const chunkRel = m[2];

const chunkPath = path.resolve(entryDir, chunkRel.replace(/\.mjs$/, '.d.mts'));

if (!fs.existsSync(chunkPath)) continue;

const chunkSrc = fs.readFileSync(chunkPath, 'utf8');

// collect full type names marked @deprecated in the chunk

const deprecatedNames = new Set();

// Match /** @deprecated ... */ directly followed by a top-level type declaration

// The [^{}]* ensures we don't cross type body boundaries

const depRe = /\/\*\*\s*@deprecated[^{}]*?\*\/\s*(?:export\s+)?type\s+(\w+)/g;

let dm;

while ((dm = depRe.exec(chunkSrc))) {

deprecatedNames.add(dm[1]);

}

// map import specifiers (alias as ExportedName) back to chunk names

// entry: "d as ConditionDefinition" -> chunk exports "ConditionDefinition as d"

// so we check if ExportedName is deprecated in the chunk

for (const spec of specifiers.split(',')) {

const parts = spec.trim().split(/\s+as\s+/);

if (parts.length !== 2) continue;

const exportedName = parts[1];

if (deprecatedNames.has(exportedName)) {

deprecated.add(exportedName);

}

return deprecated;

}

/**

* Annotate `type Foo` entries in the export block with `/** @deprecated *\/` if

* the underlying declaration was marked deprecated in a chunk file.

* @param {string} cleaned

* @param {Set<string>} deprecated

* @returns {string}

function annotateDeprecatedExports(cleaned, deprecated) {

if (deprecated.size === 0) return cleaned;

// match "type Name" inside export { ... } blocks

return cleaned.replace(/\btype\s+(\w+)/g, (match, name) => {

if (deprecated.has(name)) {

return `/** @deprecated */ type ${name}`;

}

return match;

});

}

/** @returns {Promise<number>} number of api-surface files written */

export async function generateApiSurface() {

let generated = 0;

for (const pkg of packages) {

const dtsPath = path.resolve(ROOT, pkg.dts);

if (!fs.existsSync(dtsPath)) {

console.warn(` skipped ${pkg.name} - ${pkg.dts} not found (run build first)`);

continue;

}

const raw = fs.readFileSync(dtsPath, 'utf8');

const deprecated = collectDeprecatedFromChunks(raw, path.dirname(dtsPath));

let cleaned = clean(raw);

cleaned = annotateDeprecatedExports(cleaned, deprecated);

const header =

`# ${pkg.name} - Public API Surface\n\n` +

`\n\n` +

'```ts\n';

const footer = '```\n';

const outPath = path.resolve(ROOT, pkg.out);

fs.writeFileSync(outPath, header + cleaned + footer, 'utf8');

await formatWithOxfmt(outPath);

generated++;

console.log(` ${pkg.name} -> ${pkg.out}`);

}

if (generated === 0) {

console.warn('No .d.mts files found - run `pnpm build` first.');

process.exit(1);

}

return generated;

}

const isMain = process.argv[1] && import.meta.filename === path.resolve(process.argv[1]);

if (isMain) {

generateApiSurface().catch((err) => {

console.error(err);

process.exit(1);

});

}

Sunbelt Computer Software

PL/B Language Development and Support

Navigation Menu

Uh oh!

Uh oh!

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Uh oh!

FilesExpand file tree

generate-api-surface.js

Latest commit

History

generate-api-surface.js

File metadata and controls