refactor(validation): decompose DTD attribute checks into per-constraint rules (#101)

This commit is contained in:
Mihaela Mihaljevic 2026-06-09 04:28:03 +02:00
parent 3391f595a2
commit 506c502602
5 changed files with 135 additions and 41 deletions

View File

@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Changed
- DTD attribute validation is now decomposed into five named, independently composable `Validation` rules (#101): `DTD.requiredAttributes`, `fixedAttributeValues`, `enumeratedAttributeValues`, `tokenizedAttributeTypes`, and `notationAttributes`, replacing the single `attributeDeclarations` rule. Each is removable by identity and isolation-tested one constraint at a time, honoring the validation-framework idiom. Behavior is unchanged. (XSD content validation stays one recursive rule by a documented scope decision, since its constraints are interdependent through type resolution; Schematron already exposes its rules as composable `Validation<Node, Void>` values.)
### Added
- XInclude range inclusion (#87), completing the XInclude audit. An `xi:include` whose `xpointer` selects a range (`xpointer(range(...))`, `range-to`, or `string-range`) now includes that range's content: when no node-selecting scheme matches, the processor falls back to the XPointer range model and substitutes each range's spanned nodes (or the matched text for a `string-range`).

View File

@ -77,9 +77,9 @@ flowchart TB
classDef epic fill:#f2e5ff,stroke:#af52de,color:#111827
classDef todo fill:#f2f4f7,stroke:#8e8e93,color:#111827
Epic71["#71 Beyond-parity libxml2 audit"]:::epic
AuditDone["Closed in main: DTD #72 #73, XSD #75 #76 #77 #78, parsing #95 #96 #98 #100, regex #89, catalog #86, XSLT #81 #82, RELAX NG #79, Schematron #80, DOM #90, serialization #91, C14N #85, XPath/XPointer #88, XInclude #87"]:::done
AuditDone["Closed in main: DTD #72 #73, XSD #75 #76 #77 #78, parsing #95 #96 #98 #100, regex #89, catalog #86, XSLT #81 #82, RELAX NG #79, Schematron #80, DOM #90, serialization #91, C14N #85, XPath/XPointer #88, XInclude #87, validators #101"]:::done
Epic74["#74 Parser-breadth sub-epic: standalone/decl #95, XML 1.1 #96, reader #98, recovery #100 done; encodings #97 #99 open"]:::epic
Open["Open: HTML5 #83 #84, encoding tables #97 #99, validator decomposition #101"]:::todo
Open["Open: HTML5 #83 #84, encoding tables #97 #99"]:::todo
Epic71 --> AuditDone
AuditDone --> Epic74
Epic74 --> Open
@ -89,7 +89,7 @@ flowchart TB
PureXML is a working, dependency-free XML library today: parse, emit, validate,
query, and stream documents on macOS, Linux, Windows, and WASM. The test suite
currently runs **699 tests in 111 suites** (`swift test`).
currently runs **703 tests in 111 suites** (`swift test`).
### Shipped (libxml2-aligned surface)

View File

@ -75,35 +75,34 @@ extension PureXML.Validation.DTD {
// MARK: Attributes
static func attributeViolations(
_ declaration: PureXML.Validation.AttributeDeclaration,
on element: DTDElement,
schema: PureXML.Validation.DTDSchema,
at path: DTDPath,
) -> [DTDFailure] {
let name = element.name.description
let value = element.attributes.first {
/// The value supplied for a declaration's attribute on an element, or nil when
/// it is absent.
static func attributeValue(of declaration: PureXML.Validation.AttributeDeclaration, on element: DTDElement) -> String? {
element.attributes.first {
$0.name.description == declaration.name || $0.name.localName == declaration.name
}?.value
guard let value else {
return declaration.defaultDecl == .required
? [DTDFailure(reason: "required attribute '\(declaration.name)' is missing on <\(name)>", at: path)]
: []
}
var result: [DTDFailure] = []
if case let .fixed(fixedValue) = declaration.defaultDecl, value != fixedValue {
result.append(DTDFailure(reason: "attribute '\(declaration.name)' on <\(name)> is #FIXED and must be \"\(fixedValue)\"", at: path))
}
if case let .enumeration(allowed) = declaration.type, !allowed.contains(value) {
result.append(DTDFailure(reason: "attribute '\(declaration.name)' on <\(name)> has a value outside its enumeration", at: path))
}
if let tokenError = tokenizedTypeError(declaration, value: value, on: name, entities: schema.unparsedEntities, at: path) {
result.append(tokenError)
}
if let notationError = notationError(declaration, value: value, on: name, notations: schema.notations, at: path) {
result.append(notationError)
}
return result
}
/// The error when a `#REQUIRED` attribute is absent.
static func requiredViolation(_ declaration: PureXML.Validation.AttributeDeclaration, on element: DTDElement, at path: DTDPath) -> DTDFailure? {
guard declaration.defaultDecl == .required, attributeValue(of: declaration, on: element) == nil else { return nil }
return DTDFailure(reason: "required attribute '\(declaration.name)' is missing on <\(element.name.description)>", at: path)
}
/// The error when a `#FIXED` attribute is present with a value other than the
/// fixed one.
static func fixedViolation(_ declaration: PureXML.Validation.AttributeDeclaration, on element: DTDElement, at path: DTDPath) -> DTDFailure? {
guard case let .fixed(fixedValue) = declaration.defaultDecl,
let value = attributeValue(of: declaration, on: element), value != fixedValue else { return nil }
return DTDFailure(reason: "attribute '\(declaration.name)' on <\(element.name.description)> is #FIXED and must be \"\(fixedValue)\"", at: path)
}
/// The error when an enumerated attribute is present with a value outside its
/// list.
static func enumerationViolation(_ declaration: PureXML.Validation.AttributeDeclaration, on element: DTDElement, at path: DTDPath) -> DTDFailure? {
guard case let .enumeration(allowed) = declaration.type,
let value = attributeValue(of: declaration, on: element), !allowed.contains(value) else { return nil }
return DTDFailure(reason: "attribute '\(declaration.name)' on <\(element.name.description)> has a value outside its enumeration", at: path)
}
/// The error when a `NOTATION` attribute value is not one of the names its

View File

@ -14,7 +14,9 @@ public extension PureXML.Validation {
/// be declared.
static func validator(strict: Bool) -> Validator<DTDSchema> {
var validator = Validator<DTDSchema>.blank
.validating(contentModel, attributeDeclarations)
.validating(contentModel)
.validating(requiredAttributes, fixedAttributeValues, enumeratedAttributeValues)
.validating(tokenizedAttributeTypes, notationAttributes)
.validating(identifierIntegrity)
if strict { validator = validator.validating(undeclaredElement) }
return validator
@ -29,19 +31,67 @@ public extension PureXML.Validation {
}
}
/// Each element's attributes satisfy their `<!ATTLIST>` declarations
/// (required presence, `#FIXED` value, and enumerations).
static var attributeDeclarations: Validation<DTDElement, DTDSchema> {
.init(description: "Element attributes satisfy their DTD declarations") { context in
/// Every `#REQUIRED` attribute declared for an element is present.
static var requiredAttributes: Validation<DTDElement, DTDSchema> {
attributeRule("Required DTD attributes are present") { declaration, element, path in
requiredViolation(declaration, on: element, at: path)
}
}
/// Every `#FIXED` attribute, when present, holds its fixed value.
static var fixedAttributeValues: Validation<DTDElement, DTDSchema> {
attributeRule("#FIXED DTD attributes hold their fixed value") { declaration, element, path in
fixedViolation(declaration, on: element, at: path)
}
}
/// Every enumerated attribute, when present, holds a value from its list.
static var enumeratedAttributeValues: Validation<DTDElement, DTDSchema> {
attributeRule("Enumerated DTD attributes hold a listed value") { declaration, element, path in
enumerationViolation(declaration, on: element, at: path)
}
}
/// Every tokenized attribute (`NMTOKEN(S)`, `ENTITY`/`ENTITIES`), when
/// present, matches its declared lexical form.
static var tokenizedAttributeTypes: Validation<DTDElement, DTDSchema> {
.init(description: "Tokenized DTD attributes match their declared type") { context in
let element = context.subject
guard let declarations = context.document.attributes[element.name.description] else { return [] }
let schema = context.document
return declarations.flatMap { declaration in
attributeViolations(declaration, on: element, schema: schema, at: context.codingPath)
return (schema.attributes[element.name.description] ?? []).compactMap { declaration in
attributeValue(of: declaration, on: element).flatMap { value in
tokenizedTypeError(declaration, value: value, on: element.name.description, entities: schema.unparsedEntities, at: context.codingPath)
}
}
}
}
/// Every `NOTATION` attribute, when present, names a declared, listed
/// notation.
static var notationAttributes: Validation<DTDElement, DTDSchema> {
.init(description: "NOTATION DTD attributes name a declared notation") { context in
let element = context.subject
let schema = context.document
return (schema.attributes[element.name.description] ?? []).compactMap { declaration in
attributeValue(of: declaration, on: element).flatMap { value in
notationError(declaration, value: value, on: element.name.description, notations: schema.notations, at: context.codingPath)
}
}
}
}
/// Builds a per-declaration attribute rule: the `check` is applied to each
/// `<!ATTLIST>` declaration for the element, gathering one failure each.
private static func attributeRule(
_ description: String,
_ check: @escaping (PureXML.Validation.AttributeDeclaration, DTDElement, DTDPath) -> DTDFailure?,
) -> Validation<DTDElement, DTDSchema> {
.init(description: description) { context in
let element = context.subject
return (context.document.attributes[element.name.description] ?? []).compactMap { check($0, element, context.codingPath) }
}
}
/// In strict mode, every element is declared in the DTD.
static var undeclaredElement: Validation<DTDElement, DTDSchema> {
.init(description: "Element is declared in the DTD") { context in

View File

@ -45,17 +45,58 @@ struct ValidationRuleTests {
#expect(path(errors[0]) == ["r"])
}
@Test("DTD.attributeDeclarations reports a missing required attribute")
func test_attributeDeclarations() throws {
@Test("DTD.requiredAttributes reports a missing required attribute in isolation")
func test_requiredAttributes() throws {
let (node, schema) = try dtd("<!DOCTYPE r [<!ELEMENT r EMPTY><!ATTLIST r id CDATA #REQUIRED>]><r/>")
let errors = PureXML.Validation.Validator<DTDSchema>.blank
.validating(PureXML.Validation.DTD.attributeDeclarations)
.validating(PureXML.Validation.DTD.requiredAttributes)
.errors(for: node, in: schema)
#expect(errors.count == 1)
#expect(errors.first?.reason == "required attribute 'id' is missing on <r>")
#expect(path(errors[0]) == ["r"])
}
@Test("DTD.fixedAttributeValues isolates the #FIXED constraint")
func test_fixedAttributeValues() throws {
// A missing required attribute is invisible to the fixed-value rule alone.
let (node, schema) = try dtd("<!DOCTYPE r [<!ELEMENT r EMPTY><!ATTLIST r v CDATA #FIXED \"1\" id CDATA #REQUIRED>]><r v=\"2\"/>")
let errors = PureXML.Validation.Validator<DTDSchema>.blank
.validating(PureXML.Validation.DTD.fixedAttributeValues)
.errors(for: node, in: schema)
#expect(errors.count == 1)
#expect(errors.first?.reason == "attribute 'v' on <r> is #FIXED and must be \"1\"")
}
@Test("DTD.enumeratedAttributeValues isolates the enumeration constraint")
func test_enumeratedAttributeValues() throws {
let (node, schema) = try dtd("<!DOCTYPE r [<!ELEMENT r EMPTY><!ATTLIST r k (a|b) #IMPLIED>]><r k=\"z\"/>")
let errors = PureXML.Validation.Validator<DTDSchema>.blank
.validating(PureXML.Validation.DTD.enumeratedAttributeValues)
.errors(for: node, in: schema)
#expect(errors.count == 1)
#expect(errors.first?.reason == "attribute 'k' on <r> has a value outside its enumeration")
}
@Test("DTD.tokenizedAttributeTypes isolates the NMTOKEN constraint")
func test_tokenizedAttributeTypes() throws {
let (node, schema) = try dtd("<!DOCTYPE r [<!ELEMENT r EMPTY><!ATTLIST r t NMTOKEN #IMPLIED>]><r t=\"a b\"/>")
let errors = PureXML.Validation.Validator<DTDSchema>.blank
.validating(PureXML.Validation.DTD.tokenizedAttributeTypes)
.errors(for: node, in: schema)
#expect(errors.count == 1)
#expect(errors.first?.reason.contains("NMTOKEN") == true)
}
@Test("DTD.notationAttributes isolates the NOTATION constraint")
func test_notationAttributes() throws {
let (node, schema) = try dtd("<!DOCTYPE r [<!ELEMENT r EMPTY><!ATTLIST r kind NOTATION (bmp) #IMPLIED>]><r kind=\"bmp\"/>")
let errors = PureXML.Validation.Validator<DTDSchema>.blank
.validating(PureXML.Validation.DTD.notationAttributes)
.errors(for: node, in: schema)
#expect(errors.count == 1)
#expect(errors.first?.reason.contains("undeclared notation") == true)
}
@Test("DTD.undeclaredElement uses the single-error Bool form (Failed to satisfy)")
func test_undeclaredElement() throws {
let (node, schema) = try dtd("<!DOCTYPE r [<!ELEMENT a EMPTY>]><r/>")