preserve jsdoc and navigation for homomorphic keys (#1341)

Author: ssalbdivad

ark/attest/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 NOTE: This changelog is incomplete, but will include notable attest-specific changes (many updates consist almost entirely of bumped `arktype` versions for assertions).
 
+## 0.44.0
+
+Support assertions for JSDoc contents associated with an `attest`ed value
+
+```ts
+const t = type({
+	/** FOO */
+	foo: "string"
+})
+
+const out = t.assert({ foo: "foo" })
+
+// match or snapshot expected jsdoc associated with the value passed to attest
+attest(out.foo).jsdoc.snap("FOO")
+```
+
 ## 0.41.0
 
 ### Bail early for obviously incorrect `equals` comparisons

ark/attest/README.md

@@ -112,6 +112,18 @@ describe("attest features", () => {
 		attest({ "f": "🐐" } as Legends).completions({ "f": ["faker"] })
 	})
 
+	it("jsdoc snapshotting", () => {
+		// match or snapshot expected jsdoc associated with the value passed to attest
+		const t = type({
+			/** FOO */
+			foo: "string"
+		})
+
+		const out = t.assert({ foo: "foo" })
+
+		attest(out.foo).jsdoc.snap("FOO")
+	})
+
 	it("integrate runtime logic with type assertions", () => {
 		const arrayOf = type("<t>", "t[]")
 		const numericArray = arrayOf("number | bigint")

ark/attest/__tests__/assertions.test.ts

@@ -180,4 +180,25 @@ Actual: string`)
 Expected: {"a":"five"}
 Actual: ArkErrors`)
 	})
+
+	it("jsdoc ", () => {
+		type O = {
+			/** FOO */
+			foo: string
+			bar: number
+		}
+
+		const o: O = {
+			foo: "foo",
+			bar: 5
+		}
+
+		attest(o.foo).jsdoc.equals("FOO")
+
+		assert.throws(
+			() => attest(o.bar).jsdoc.equals("BAR"),
+			assert.AssertionError,
+			"BAR"
+		)
+	})
 })

ark/attest/assert/chainableAssertions.ts

@@ -234,6 +234,16 @@ export class ChainableAssertions implements AssertionRecord {
 		return this.snap
 	}
 
+	get jsdoc(): any {
+		if (this.ctx.cfg.skipTypes) return chainableNoOpProxy
+
+		this.ctx.versionableActual = new TypeAssertionMapping(data => ({
+			actual: formatTypeString(data.jsdoc ?? "")
+		}))
+		this.ctx.allowRegex = true
+		return this.immediateOrChained()
+	}
+
 	get type(): any {
 		if (this.ctx.cfg.skipTypes) return chainableNoOpProxy
 
@@ -351,6 +361,7 @@ export type comparableValueAssertion<expected, kind extends AssertionKind> = {
 	instanceOf: (constructor: Constructor) => nextAssertions<kind>
 	is: (value: expected) => nextAssertions<kind>
 	completions: CompletionsSnap
+	jsdoc: comparableValueAssertion<string, kind>
 	satisfies: <const def>(
 		def: type.validate<def> &
 			validateExpectedOverlaps<expected, type.infer.In<def>>

ark/attest/cache/utils.ts

@@ -11,10 +11,7 @@ import {
 	getTsConfigInfoOrThrow,
 	getTsLibFiles
 } from "./ts.ts"
-import type {
-	AssertionsByFile,
-	LinePositionRange
-} from "./writeAssertionCache.ts"
+import type { LinePositionRange } from "./writeAssertionCache.ts"
 
 export const getCallLocationFromCallExpression = (
 	callExpression: ts.CallExpression
@@ -41,15 +38,16 @@ export const getCallLocationFromCallExpression = (
 	return location
 }
 
+/**
+ * Processes inline instantiations from an attest call
+ * Preserves any JSDoc comments that are associated with the original expression
+ */
 export const gatherInlineInstantiationData = (
 	file: ts.SourceFile,
-	fileAssertions: AssertionsByFile,
-	attestAliasInstantiationMethodCalls: string[]
+	assertionsByFile: Record<string, any[]>,
+	instantiationMethodCalls: string[]
 ): void => {
-	const expressions = getCallExpressionsByName(
-		file,
-		attestAliasInstantiationMethodCalls
-	)
+	const expressions = getCallExpressionsByName(file, instantiationMethodCalls)
 	if (!expressions.length) return
 
 	const enclosingFunctions = expressions.map(expression => {
@@ -81,8 +79,8 @@ ${enclosingFunction.ancestor.getText()}`
 			count: getInstantiationsContributedByNode(file, body)
 		}
 	})
-	const assertions = fileAssertions[getFileKey(file.fileName)] ?? []
-	fileAssertions[getFileKey(file.fileName)] = [
+	const assertions = assertionsByFile[getFileKey(file.fileName)] ?? []
+	assertionsByFile[getFileKey(file.fileName)] = [
 		...assertions,
 		...instantiationInfo
 	]

ark/attest/cache/writeAssertionCache.ts

@@ -68,13 +68,99 @@ export const analyzeAssertCall = (
 	const typeArgs = types.typeArgs.map(typeArg => serializeArg(typeArg, types))
 	const errors = checkDiagnosticMessages(assertCall, diagnosticsByFile)
 	const completions = getCompletions(assertCall)
-	return {
+
+	// Extract JSDoc comment for first argument if available
+	const jsdoc = extractJSDocFromArgument(assertCall)
+
+	const result: TypeAssertionData = {
 		location,
 		args,
 		typeArgs,
 		errors,
 		completions
 	}
+
+	if (jsdoc) result.jsdoc = jsdoc
+
+	return result
+}
+
+/**
+ * Extract JSDoc comments associated with the first argument of a call expression
+ */
+const extractJSDocFromArgument = (
+	callExpr: ts.CallExpression
+): string | undefined => {
+	// We're only interested in the first argument
+	const firstArg = callExpr.arguments[0]
+	if (!firstArg) return undefined
+
+	const checker = getInternalTypeChecker()
+
+	// If the argument is a property access expression (e.g., out.foo)
+	if (ts.isPropertyAccessExpression(firstArg)) {
+		// Try to find the symbol for the property
+		const propSymbol = checker.getSymbolAtLocation(firstArg)
+		if (propSymbol) {
+			// Get JSDoc from property declarations
+			return getJSDocFromSymbol(propSymbol)
+		}
+	}
+	// If argument is an identifier, try to find its declaration's JSDoc
+	else if (ts.isIdentifier(firstArg)) {
+		const symbol = checker.getSymbolAtLocation(firstArg)
+		if (symbol) return getJSDocFromSymbol(symbol)
+	}
+
+	return undefined
+}
+
+/**
+ * Extract JSDoc comments from a symbol's declarations
+ */
+const getJSDocFromSymbol = (symbol: ts.Symbol): string | undefined => {
+	// Get JSDoc directly from the symbol if possible
+	const symbolDocumentation = ts.displayPartsToString(
+		symbol.getDocumentationComment(getInternalTypeChecker())
+	)
+	if (symbolDocumentation) return symbolDocumentation.trim()
+
+	// If no symbol documentation, try to get JSDoc from declarations
+	const declarations = symbol.getDeclarations() || []
+	for (const declaration of declarations) {
+		// For property declarations in object literals, get the JSDoc comment
+		if (
+			ts.isPropertyAssignment(declaration) ||
+			ts.isShorthandPropertyAssignment(declaration) ||
+			ts.isPropertyDeclaration(declaration)
+		) {
+			const jsDocTags = ts.getJSDocTags(declaration)
+			if (jsDocTags.length > 0) {
+				return jsDocTags
+					.map(tag => {
+						const comment = tag.comment?.toString() || ""
+						return tag.tagName.text + (comment ? ` ${comment}` : "")
+					})
+					.join("\n")
+			}
+
+			// Try to get JSDoc comment before the property
+			const jsDocComments = ts.getJSDocCommentsAndTags(declaration)
+			if (jsDocComments && jsDocComments.length > 0) {
+				return jsDocComments
+					.map(doc => {
+						if (ts.isJSDoc(doc)) return doc.comment || ""
+
+						return ""
+					})
+					.filter(Boolean)
+					.join("\n")
+					.trim()
+			}
+		}
+	}
+
+	return undefined
 }
 
 const serializeArg = (
@@ -197,6 +283,8 @@ export type TypeRelationshipAssertionData = {
 	typeArgs: ArgAssertionData[]
 	errors: string[]
 	completions: Completions
+	/** JSDoc comment for the first argument, if any */
+	jsdoc?: string
 }
 
 export type TypeBenchmarkingAssertionData = {

ark/attest/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ark/attest",
-	"version": "0.43.4",
+	"version": "0.44.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",

ark/fs/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ark/fs",
-	"version": "0.43.4",
+	"version": "0.44.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",

ark/repo/scratch.ts

@@ -1,12 +1,13 @@
 import { type } from "arktype"
 
-const types = type.module(
-	{
-		foo: {
-			test: "string = 'test'"
-		}
-	},
-	{ jitless: true }
-)
+const t = type({
+	/** FOO */
+	foo: "string",
+	/** BAR */
+	bar: "number?"
+})
 
-types.foo({}) //?
+const out = t.assert({ foo: "foo" })
+
+out.foo
+out.bar

ark/schema/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ark/schema",
-	"version": "0.43.4",
+	"version": "0.44.0",
 	"license": "MIT",
 	"author": {
 		"name": "David Blass",