docs/scripts/validate-content-api.ts at docs/api-validation · cipherstash/docs · GitHub

History

224 lines (208 loc) · 8.48 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

#!/usr/bin/env tsx

/**

* Content API gate.

* Fails the build when documentation teaches one of the specific APIs listed in

* RULES below. Two long-lived content branches plus a fast-moving SDK means a

* page fixed on one branch can be silently reintroduced by a port from the

* other — which is exactly how the deprecated `LockContext.identify()` flow

* survived a fix and came back in a comparison-page port.

* ── What this does NOT do ──────────────────────────────────────────────────

* This is a DENYLIST, not verification. It catches only what someone thought to

* add, and cannot see an API that changed MEANING rather than name. Stack's

* `contains()` → `matches()` rename is the worked example: `contains()` still

* exists, so nothing here (or in any symbol-presence diff) fires, yet calling it

* on an encrypted text column now raises. That shipped in the docs.

* Catching that class needs the examples themselves typechecked against the

* installed SDK, the way Rust doctests are compiled. Until then, treat a pass

* as "none of the known-bad patterns appeared", which is what it prints.

* Run via `bun run validate-content`; wired into prebuild.

* A line is exempt if it also says the API is retired ("deprecated", "removed",

* "no longer", "are gone"), so that callouts and migration notes are free to

* name the old API in order to warn readers off it. The check is deliberately

* line-local: naming a dead symbol without saying it is dead is the bug.

* Generated output is skipped: it mirrors the SDK's own doc comments, which we

* fix upstream rather than here.

import fs from "node:fs";

import path from "node:path";

/** Generated by scripts/*, or a version reference that documents old syntax on purpose. */

const SKIP_PATHS = [

"content/stack/reference/stack/", // TypeDoc output

"content/docs/reference/stack/", // TypeDoc output (post-repoint)

"content/stack/reference/eql/index.mdx", // generated EQL API reference

"content/docs/reference/eql/functions.mdx", // generated

"content/docs/reference/cli/", // generated from `stash manifest --json`

"content/docs/reference/eql/v2/", // the retained EQL v2 reference

];

/**

* Prose that names a retired API in order to warn readers off it. Kept narrow:

* these are the words we actually use in deprecation callouts and migration

* notes, not a general escape hatch.

const RETIRED_MARKER =

type Rule = {

id: string;

pattern: RegExp;

message: string;

fix: string;

/** Only apply the rule to files under these prefixes. */

scope: string[];

};

const IDENTITY_SCOPE = ["content/docs/", "content/stack/"];

/** The legacy tree documents EQL v2 throughout; only the v2 IA must be v3-only. */

const V3_SCOPE = ["content/docs/"];

const RULES: Rule[] = [

{

id: "lockcontext-identify",

pattern: /\.identify\s*\(/,

message:

"`LockContext.identify()` is deprecated. Per-operation CTS tokens were removed in protect-ffi 0.25; the token it fetches no longer affects encryption.",

fix: 'Authenticate the client with `OidcFederationStrategy` via `config.authStrategy`, then pass the claim to `.withLockContext({ identityClaim: ["sub"] })`.',

scope: IDENTITY_SCOPE,

{

id: "identity-token-option",

pattern: /identityToken\s*:/,

message:

"`withLockContext({ identityToken })` has never existed in any released version of @cipherstash/stack.",

fix: 'Use `.withLockContext({ identityClaim: ["sub"] })` on the operation, not on the client.',

scope: IDENTITY_SCOPE,

{

id: "bare-lockcontext-constructor",

pattern: /new\s+LockContext\s*$\s*$/,

message:

"A bare `new LockContext()` is only useful with the deprecated `identify()` flow.",

fix: 'Pass a plain `{ identityClaim: ["sub"] }` to `.withLockContext()`. The Supabase query builder still requires an instance: `new LockContext({ context: { identityClaim: ["sub"] } })`.',

scope: IDENTITY_SCOPE,

{

id: "eql-v2-encrypted-type",

pattern: /\beql_v2_encrypted\b/,

message: "The `eql_v2_encrypted` column type was removed in EQL 3.0.0.",

fix: "Type the column with an EQL v3 domain variant, e.g. `public.text_eq`. See /reference/eql/core-concepts.",

scope: V3_SCOPE,

{

id: "eql-v2-schema-functions",

pattern: /\beql_v2\.\w+\s*\(/,

message: "The `eql_v2` schema was removed in EQL 3.0.0.",

fix: "Use the `eql_v3` equivalents, or the encrypted operators directly with a typed operand.",

scope: V3_SCOPE,

{

id: "eql-v2-config-table",

pattern:

message:

"EQL v3 has no database-side configuration table; these functions are gone.",

fix: "A column's searchable capability is fixed by the domain variant it is typed as. See /reference/eql/core-concepts.",

scope: V3_SCOPE,

{

id: "protect-branding",

pattern: /\b(ProtectClientConfig|@cipherstash\/cli)\b/,

message:

"Stale naming from before the `protect` -> `stack` rename, or the `@cipherstash/cli` -> `stash` rename.",

fix: "Use `EncryptionClientConfig` and `stash`.",

scope: V3_SCOPE,

];

type Finding = {

file: string;

line: number;

rule: Rule;

text: string;

};

function collectFiles(dir: string): string[] {

if (!fs.existsSync(dir)) return [];

const files: string[] = [];

for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {

const full = path.join(dir, entry.name);

if (entry.isDirectory()) files.push(...collectFiles(full));

else if (/\.mdx?$/.test(entry.name)) files.push(full);

}

return files;

}

function isSkipped(relative: string): boolean {

return SKIP_PATHS.some((prefix) => relative.startsWith(prefix));

}

function inScope(relative: string, rule: Rule): boolean {

return rule.scope.some((prefix) => relative.startsWith(prefix));

}

const root = process.cwd();

const findings: Finding[] = [];

let filesScanned = 0;

let filesSkipped = 0;

for (const dir of ["content/docs", "content/stack"]) {

for (const file of collectFiles(path.join(root, dir))) {

const relative = path.relative(root, file).split(path.sep).join("/");

if (isSkipped(relative)) {

filesSkipped++;

continue;

}

filesScanned++;

const lines = fs.readFileSync(file, "utf8").split("\n");

lines.forEach((text, i) => {

// A line that names a dead API *and says it is dead* is doing its job.

if (RETIRED_MARKER.test(text)) return;

for (const rule of RULES) {

if (!inScope(relative, rule)) continue;

if (rule.pattern.test(text)) {

findings.push({

file: relative,

line: i + 1,

rule,

text: text.trim(),

});

}

});

}

if (findings.length > 0) {

const byRule = new Map<string, Finding[]>();

for (const f of findings) {

const list = byRule.get(f.rule.id) ?? [];

list.push(f);

byRule.set(f.rule.id, list);

}

console.error(

`✗ ${findings.length} occurrence(s) of deprecated or non-existent API in documentation:\n`,

);

for (const [id, group] of byRule) {

const { message, fix } = group[0].rule;

console.error(` [${id}] ${message}`);

console.error(` Fix: ${fix}\n`);

for (const f of group) {

console.error(` ${f.file}:${f.line}`);

console.error(` ${f.text.slice(0, 100)}`);

}

console.error("");

}

console.error(

'A line that also says the API is retired ("deprecated", "removed", "no longer",\n' +

'"are gone", "never existed") is exempt, so deprecation callouts still pass.',

);

process.exit(1);

}

// Say what was actually checked. This gate is a DENYLIST: it can only catch the

// APIs listed in RULES, so an unqualified "no non-existent API found" overstates

// it — and did, while `content/docs/reference/stack/supabase.mdx` taught

// `.contains()` for encrypted free-text, which raises. Reporting the rule count

// makes the coverage legible at a glance, so the next reader can tell the

// difference between "verified" and "matched nothing on a short list".

console.log(

`✓ content API gate: no occurrences of ${RULES.length} known-retired API pattern(s) ` +

`in ${filesScanned} file(s) (${filesSkipped} generated/pinned file(s) skipped).`,

);

console.log(

" Denylist only: it does not verify that the APIs the docs DO name still exist.",

);

docs/scripts/validate-content-api.ts at docs/api-validation · cipherstash/docs · GitHub

Uh oh!

Expand file tree

Breadcrumbs

validate-content-api.ts

Latest commit

History

Breadcrumbs

validate-content-api.ts

File metadata and controls