ncs_mdes 0.2.0

data/spec/ncs_navigator/mdes/source_documents_spec.rb

@@ -0,0 +1,95 @@
+require File.expand_path("../../../spec_helper.rb", __FILE__)
+
+module NcsNavigator::Mdes
+  describe SourceDocuments do
+    before do
+      @spec_base, ENV[SourceDocuments::BASE_ENV_VAR] = ENV[SourceDocuments::BASE_ENV_VAR], nil
+    end
+
+    after do
+      ENV[SourceDocuments::BASE_ENV_VAR] = @spec_base
+    end
+
+    describe '#base' do
+      let(:base) { SourceDocuments.new.base }
+
+      it 'defaults to the documents directory in the gem' do
+        base.should == File.expand_path('../../../../documents', __FILE__)
+      end
+
+      it 'can be overridden using the NCS_MDES_DOCS_DIR environment variable' do
+        ENV['NCS_MDES_DOCS_DIR'] = '/etc/foo'
+        base.should == '/etc/foo'
+      end
+    end
+
+    describe '#schema' do
+      let(:docs) { SourceDocuments.new }
+
+      before do
+        docs.base = '/baz'
+      end
+
+      it 'absolutizes a relative path against the base' do
+        docs.schema = '1.3/bar.xsd'
+        docs.schema.should == '/baz/1.3/bar.xsd'
+      end
+
+      it 'leaves an absolute path alone' do
+        docs.schema = '/somewhere/particular.xsd'
+        docs.schema.should == '/somewhere/particular.xsd'
+      end
+    end
+
+    describe '.get' do
+      describe '1.2' do
+        subject { SourceDocuments.get('1.2') }
+
+        it 'has the correct path for the schema' do
+          subject.schema.should =~ %r{1.2/Data_Transmission_Schema_V1.2.xsd$}
+        end
+
+        it 'is of the specified version' do
+          subject.version.should == '1.2'
+        end
+      end
+
+      describe '2.0' do
+        subject { SourceDocuments.get('2.0') }
+
+        it 'has the correct path for the schema' do
+          subject.schema.should =~ %r{2.0/NCS_Transmission_Schema_2.0.01.02.xml$}
+        end
+
+        it 'is of the specified version' do
+          subject.version.should == '2.0'
+        end
+      end
+
+      it 'fails for an unsupported version' do
+        lambda { SourceDocuments.get('1.0') }.
+          should raise_error('MDES 1.0 is not supported by this version of ncs_mdes')
+      end
+    end
+
+    describe '.xmlns' do
+      subject { SourceDocuments.xmlns }
+
+      it 'includes the XSD namespace' do
+        subject['xs'].should == 'http://www.w3.org/2001/XMLSchema'
+      end
+
+      it 'includes the NCS namespace' do
+        subject['ncs'].should == 'http://www.nationalchildrensstudy.gov'
+      end
+
+      it 'includes the NCS doc namespace' do
+        subject['ncsdoc'].should == 'http://www.nationalchildrensstudy.gov/doc'
+      end
+
+      it 'is available from an instance also' do
+        SourceDocuments.new.xmlns.keys.sort.should == %w(ncs ncsdoc xs)
+      end
+    end
+  end
+end

data/spec/ncs_navigator/mdes/specification_spec.rb

@@ -0,0 +1,102 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+module NcsNavigator::Mdes
+  describe Specification do
+    describe '#version' do
+      it 'delegates to the source documents' do
+        Specification.new('1.2').version.should == '1.2'
+      end
+    end
+
+    describe '#initialize' do
+      it 'accepts a string version' do
+        Specification.new('2.0').version.should == '2.0'
+      end
+
+      it 'accepts a SourceDocuments instance' do
+        Specification.new(SourceDocuments.new.tap { |s| s.version = '3.1' }).version.
+          should == '3.1'
+      end
+    end
+
+    describe '#xsd' do
+      it 'is parsed' do
+        Specification.new('1.2', :log => logger).xsd.root.name.should == 'schema'
+      end
+    end
+
+    describe '#transmission_tables' do
+      it 'is composed of TransmissionTable instances' do
+        Specification.new('2.0', :log => logger).transmission_tables.first.
+          should be_a TransmissionTable
+      end
+
+      context 'in version 1.2' do
+        let!(:tables) { Specification.new('1.2', :log => logger).transmission_tables }
+
+        it 'has 124 tables' do
+          tables.size.should == 124
+        end
+
+        it 'emits no warnings' do
+          logger[:warn].should == []
+        end
+
+        it 'resolves all NCS type references' do
+          tables.collect { |table|
+            table.variables.collect { |v| v.type }.select { |t| t.reference? }
+          }.flatten.collect { |t| t.name }.select { |n| n =~ /^ncs:/ }.should == []
+        end
+      end
+
+      context 'in version 2.0' do
+        let!(:tables) { Specification.new('2.0', :log => logger).transmission_tables }
+
+        it 'has 264 tables' do
+          tables.size.should == 264
+        end
+
+        it 'emits no warnings' do
+          logger[:warn].should == []
+        end
+
+        it 'resolves all NCS type references' do
+          tables.collect { |table|
+            table.variables.collect { |v| v.type }.select { |t| t.reference? }
+          }.flatten.collect { |t| t.name }.select { |n| n =~ /^ncs:/ }.should == []
+        end
+      end
+    end
+
+    describe '#types' do
+      it 'is composed of VariableType instances' do
+        Specification.new('2.0', :log => logger).types.first.
+          should be_a VariableType
+      end
+
+      context 'in version 1.2' do
+        let!(:types) { Specification.new('1.2', :log => logger).types }
+
+        it 'has 281 types' do
+          types.size.should == 281
+        end
+
+        it 'emits no warnings' do
+          logger[:warn].size.should == 0
+        end
+      end
+
+      context 'in version 2.0' do
+        let!(:types) { Specification.new('2.0', :log => logger).types }
+
+        it 'has 423 types' do
+          types.size.should == 423
+        end
+
+        it 'emits no warnings' do
+          logger[:warn].size.should == 0
+        end
+      end
+    end
+  end
+end

data/spec/ncs_navigator/mdes/transmission_table_spec.rb

@@ -0,0 +1,89 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+require 'nokogiri'
+
+module NcsNavigator::Mdes
+  describe TransmissionTable do
+    describe '.from_element' do
+      let(:element) {
+        Nokogiri::XML(<<-XSD).root.xpath('//xs:element[@name="study_center"]').first
+<xs:schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:fn="http://www.w3.org/2005/xpath-functions" xmlns:ncs="http://www.nationalchildrensstudy.gov" xmlns:ncsdoc="http://www.nationalchildrensstudy.gov/doc" xmlns:xlink="http://www.w3.org/TR/WD-xlink" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.nationalchildrensstudy.gov" elementFormDefault="unqualified" attributeFormDefault="unqualified">
+  <xs:element name="transmission_tables">
+    <xs:complexType>
+      <xs:sequence>
+        <xs:element name="study_center" minOccurs="0" maxOccurs="unbounded">
+          <xs:complexType>
+            <xs:sequence>
+              <xs:element name="sc_id" ncsdoc:pii="" ncsdoc:status="1" ncsdoc:key_asso="" nillable="false" type="ncs:study_center_cl1"/>
+              <xs:element name="sc_name" ncsdoc:pii="" ncsdoc:status="1" ncsdoc:key_asso="" nillable="true">
+                <xs:simpleType>
+                  <xs:restriction base="xs:string">
+                    <xs:maxLength value="100"/>
+                  </xs:restriction>
+                </xs:simpleType>
+              </xs:element>
+              <xs:element name="comments" ncsdoc:pii="P" ncsdoc:status="1" ncsdoc:key_asso="" nillable="true">
+                <xs:simpleType>
+                  <xs:restriction base="xs:string">
+                    <xs:maxLength value="8000"/>
+                  </xs:restriction>
+                </xs:simpleType>
+              </xs:element>
+              <xs:element name="transaction_type" ncsdoc:pii="" ncsdoc:status="1" ncsdoc:key_asso="" nillable="true">
+                <xs:simpleType>
+                  <xs:restriction base="xs:string">
+                    <xs:maxLength value="36"/>
+                  </xs:restriction>
+                </xs:simpleType>
+              </xs:element>
+            </xs:sequence>
+          </xs:complexType>
+        </xs:element>
+      </xs:sequence>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>
+XSD
+      }
+
+      subject { TransmissionTable.from_element(element) }
+
+      it 'has the right name' do
+        subject.name.should == 'study_center'
+      end
+
+      it 'has the right variables' do
+        subject.variables.collect(&:name).
+          should == %w(sc_id sc_name comments transaction_type)
+      end
+    end
+
+    describe '#initialize' do
+      it 'accepts a name' do
+        TransmissionTable.new('study_center').name.should == 'study_center'
+      end
+    end
+
+    describe '#[]' do
+      subject {
+        TransmissionTable.new('example').tap do |t|
+          t.variables = %w(foo bar baz).collect do |n|
+            Variable.new(n)
+          end
+        end
+      }
+
+      it 'gets a variable' do
+        subject['bar'].should be_a(Variable)
+      end
+
+      it 'gets a variable by name' do
+        subject['baz'].name.should == 'baz'
+      end
+
+      it 'is nil for an unknown variable' do
+        subject['quux'].should be_nil
+      end
+    end
+  end
+end

data/spec/ncs_navigator/mdes/variable_spec.rb

@@ -0,0 +1,216 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+require 'nokogiri'
+
+module NcsNavigator::Mdes
+  describe Variable do
+    describe '.from_element' do
+      def variable(s)
+        Variable.from_element(schema_element(s), :log => logger)
+      end
+
+      let(:comments) {
+        variable(<<-XSD)
+<xs:element name="comments" ncsdoc:pii="P" ncsdoc:status="1" ncsdoc:key_asso="" nillable="true">
+ <xs:simpleType>
+  <xs:restriction base="xs:string">
+   <xs:maxLength value="8000"/>
+  </xs:restriction>
+ </xs:simpleType>
+</xs:element>
+XSD
+      }
+
+      let(:sc_id) {
+        variable('<xs:element name="sc_id" ncsdoc:pii="" ncsdoc:status="1" ncsdoc:key_asso="" nillable="false" type="ncs:study_center_cl1"/>')
+      }
+
+      it 'has the correct name' do
+        comments.name.should == 'comments'
+      end
+
+      describe '#type' do
+        context 'when embedded' do
+          it 'is a VariableType' do
+            comments.type.should be_a VariableType
+          end
+
+          it 'is parsed from the contents' do
+            comments.type.max_length.should == 8000
+          end
+
+          it 'is not a reference' do
+            comments.type.should_not be_reference
+          end
+        end
+
+        context 'when a named type' do
+          context 'with the XML schema prefix' do
+            let!(:subject) { variable('<xs:element type="xs:decimal"/>') }
+
+            it 'is a VariableType' do
+              subject.type.should be_a VariableType
+            end
+
+            it 'has a matching base type' do
+              subject.type.base_type.should == :decimal
+            end
+
+            it 'is not a reference' do
+              subject.type.should_not be_reference
+            end
+          end
+
+          context 'with another prefix' do
+            it 'is a VariableType' do
+              sc_id.type.should be_a VariableType
+            end
+
+            it 'has the name' do
+              sc_id.type.name.should == 'ncs:study_center_cl1'
+            end
+
+            it 'is a reference' do
+              sc_id.type.should be_reference
+            end
+          end
+        end
+
+        context 'when none present' do
+          let!(:subject) { variable('<xs:element name="bar"/>') }
+
+          it 'is nil' do
+            subject.type.should be_nil
+          end
+
+          it 'warns' do
+            logger[:warn].first.should == 'Could not determine a type for variable "bar" on line 2'
+          end
+        end
+      end
+
+      describe '#required?' do
+        it 'is true when not nillable' do
+          variable('<xs:element nillable="false"/>').should be_required
+        end
+
+        it 'is false when nillable' do
+          comments.should_not be_required
+        end
+      end
+
+      describe '#pii' do
+        it 'is false when blank' do
+          variable('<xs:element ncsdoc:pii=""/>').pii.should == false
+        end
+
+        it 'is true when "Y"' do
+          variable('<xs:element ncsdoc:pii="Y"/>').pii.should == true
+        end
+
+        it 'is :possible when "P"' do
+          variable('<xs:element ncsdoc:pii="P"/>').pii.should == :possible
+        end
+
+        it 'is the literal value when some other value' do
+          variable('<xs:element ncsdoc:pii="7"/>').pii.should == '7'
+        end
+
+        it 'is :unknown when not set' do
+          variable('<xs:element/>').pii.should == :unknown
+        end
+      end
+
+      describe '#status' do
+        it 'is :active for 1' do
+          variable('<xs:element ncsdoc:status="1"/>').status.should == :active
+        end
+
+        it 'is :new for 2' do
+          variable('<xs:element ncsdoc:status="2"/>').status.should == :new
+        end
+
+        it 'is :modified for 3' do
+          variable('<xs:element ncsdoc:status="3"/>').status.should == :modified
+        end
+
+        it 'is :retired for 4' do
+          variable('<xs:element ncsdoc:status="4"/>').status.should == :retired
+        end
+
+        it 'is the literal value for some other value' do
+          variable('<xs:element ncsdoc:status="P4"/>').status.should == 'P4'
+        end
+
+        it 'is nil when not set' do
+          variable('<xs:element/>').status.should be_nil
+        end
+      end
+    end
+
+    describe '#resolve_type!' do
+      let(:reference_type) { VariableType.reference('ncs:color_cl3') }
+      let(:actual_type)    { VariableType.new('color_cl3') }
+
+      let(:types) { [ actual_type ] }
+      let(:variable) {
+        Variable.new('hair_color').tap { |v| v.type = reference_type }
+      }
+
+      context 'when the type is available' do
+        it 'resolves' do
+          variable.resolve_type!(types)
+          variable.type.should be actual_type
+        end
+      end
+
+      context 'when the type is not resolvable' do
+        before { variable.resolve_type!([], :log => logger) }
+
+        it 'leaves the reference alone' do
+          variable.type.should be reference_type
+        end
+
+        it 'warns' do
+          logger[:warn].first.should == 'Undefined type ncs:color_cl3 for hair_color.'
+        end
+      end
+
+      context 'when the reference is of an unknown namespace' do
+        let(:unknown_kind_of_ref) { VariableType.reference('foo:bar') }
+
+        before {
+          variable.type = unknown_kind_of_ref
+          variable.resolve_type!(types, :log => logger)
+        }
+
+        it 'leaves it in place' do
+          variable.type.should be unknown_kind_of_ref
+        end
+
+        it 'warns' do
+          logger[:warn].first.
+            should == 'Unknown reference namespace in type "foo:bar" for hair_color'
+        end
+      end
+
+      context 'when the type is an XML Schema type' do
+        it 'ignores it' do
+          variable.type = VariableType.xml_schema_type('decimal')
+          variable.resolve_type!(types, :log => logger)
+          logger[:warn].should == []
+        end
+      end
+
+      context 'when the type is not a reference' do
+        let(:not_a_ref) { VariableType.new('ncs:color_cl3') }
+
+        it 'does nothing' do
+          variable.type = not_a_ref
+          variable.resolve_type!(types)
+          variable.type.should be not_a_ref
+        end
+      end
+    end
+  end
+end

data/spec/ncs_navigator/mdes/variable_type_spec.rb

@@ -0,0 +1,202 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+require 'nokogiri'
+
+module NcsNavigator::Mdes
+  describe VariableType do
+    describe '.from_xsd_simple_type' do
+      def vtype(body_s, name=nil)
+        VariableType.from_xsd_simple_type(schema_element(<<-XML), :log => logger)
+          <xs:simpleType #{name ? "name='#{name}'" : nil}>
+            #{body_s}
+          </xs:simpleType>
+        XML
+      end
+
+      def vtype_from_string(restriction_body, name=nil)
+        vtype(<<-XML, name)
+          <xs:restriction base="xs:string">
+            #{restriction_body}
+          </xs:restriction>
+        XML
+      end
+
+      describe 'with an unsupported restriction base' do
+        let!(:subject) { vtype('<xs:restriction base="xs:int"/>') }
+
+        it 'is nil' do
+          subject.should be_nil
+        end
+
+        it 'logs a warning' do
+          logger[:warn].first.
+            should == 'Unsupported restriction base in simpleType on line 2'
+        end
+      end
+
+      describe 'with an unsupported restriction subelement' do
+        let!(:subject) { vtype_from_string('<xs:color value="red"/>') }
+
+        it 'logs a warning' do
+          logger[:warn].first.should == 'Unsupported restriction element "color" on line 4'
+        end
+      end
+
+      describe '#name' do
+        it 'is set if there is one' do
+          vtype_from_string(nil, 'foo').name.should == 'foo'
+        end
+
+        it 'is nil if there is not one' do
+          vtype_from_string(nil, nil).name.should be_nil
+        end
+      end
+
+      describe '#max_length' do
+        it 'is set if present' do
+          vtype_from_string('<xs:maxLength value="255"/>').max_length.should == 255
+        end
+      end
+
+      describe '#min_length' do
+        it 'is set if present' do
+          vtype_from_string('<xs:minLength value="1"/>').min_length.should == 1
+        end
+      end
+
+      describe '#pattern' do
+        it 'is compiled to a regexp if present' do
+          vtype_from_string('<xs:pattern value="([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9])?"/>').
+            pattern.should == /([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9])?/
+        end
+
+        describe 'when malformed' do
+          let!(:subject) { vtype_from_string('<xs:pattern value="(["/>') }
+
+          it 'is nil if present but malformed' do
+            subject.pattern.should be_nil
+          end
+
+          it 'logs a warning' do
+            logger[:warn].first.should == 'Uncompilable pattern "([" in simpleType on line 4'
+          end
+        end
+      end
+
+      describe '#base_type' do
+        it 'is :string' do
+          vtype_from_string('<xs:maxLength value="255"/>').base_type.should == :string
+        end
+      end
+
+      it 'is not a reference' do
+        vtype_from_string('<xs:maxLength value="255"/>').should_not be_reference
+      end
+
+      describe '#code_list' do
+        context 'when there are no enumerated values' do
+          it 'is nil' do
+            vtype_from_string('<xs:maxLength value="255"/>').code_list.should be_nil
+          end
+        end
+
+        context 'when there are enumerated values' do
+          subject {
+            vtype_from_string(<<-XSD)
+              <xs:enumeration value="1" ncsdoc:label="Retired" ncsdoc:desc="Eq" ncsdoc:global_value="192-1" ncsdoc:master_cl="equipment_action"/>
+              <xs:enumeration value="2" ncsdoc:label="Sent to manufacturer" ncsdoc:desc="Eq" ncsdoc:global_value="192-2" ncsdoc:master_cl="equipment_action"/>
+              <xs:enumeration value="3" ncsdoc:label="Conducting Maintenance on Site" ncsdoc:desc="Eq" ncsdoc:global_value="192-3" ncsdoc:master_cl="equipment_action"/>
+              <xs:enumeration value="-7" ncsdoc:label="Not applicable" ncsdoc:desc="Eq" ncsdoc:global_value="99-7" ncsdoc:master_cl="missing_data"/>
+              <xs:enumeration value="-4" ncsdoc:label="Missing in Error" ncsdoc:desc="Eq" ncsdoc:global_value="99-4" ncsdoc:master_cl="missing_data"/>
+            XSD
+          }
+
+          it 'has an entry for each value' do
+            subject.code_list.collect(&:to_s).should == %w(1 2 3 -7 -4)
+          end
+
+          it 'has the description' do
+            subject.code_list.description.should == "Eq"
+          end
+        end
+      end
+    end
+
+    describe '.reference' do
+      subject { VariableType.reference('ncs:bar') }
+
+      it 'has the right name' do
+        subject.name.should == 'ncs:bar'
+      end
+
+      it 'is a reference' do
+        subject.should be_reference
+      end
+    end
+
+    describe '.xml_schema_type' do
+      subject { VariableType.xml_schema_type('int') }
+
+      it 'has no name' do
+        subject.name.should be_nil
+      end
+
+      it 'has the correct base type' do
+        subject.base_type.should == :int
+      end
+
+      it 'is not a reference' do
+        subject.should_not be_reference
+      end
+    end
+  end
+
+  describe VariableType::CodeListEntry do
+    describe '.from_xsd_enumeration' do
+      def code_list_entry(xml_s)
+        VariableType::CodeListEntry.from_xsd_enumeration(schema_element(xml_s), :log => logger)
+      end
+
+      let(:missing) {
+        code_list_entry(<<-XSD)
+          <xs:enumeration value="-4" ncsdoc:label="Missing in Error" ncsdoc:desc="" ncsdoc:global_value="99-4" ncsdoc:master_cl="missing_data"/>
+        XSD
+      }
+
+      describe '#value' do
+        it 'is set' do
+          missing.value.should == "-4"
+        end
+
+        it 'warns when missing' do
+          code_list_entry('<xs:enumeration ncsdoc:label="Foo"/>')
+          logger[:warn].first.should == 'Missing value for code list entry on line 2'
+        end
+      end
+
+      describe "#label" do
+        it 'is set' do
+          missing.label.should == "Missing in Error"
+        end
+      end
+
+      describe '#global_value' do
+        it 'is set' do
+          missing.global_value.should == '99-4'
+        end
+      end
+
+      describe '#master_cl' do
+        it 'is set' do
+          missing.master_cl.should == 'missing_data'
+        end
+      end
+    end
+
+    describe '#to_s' do
+      it 'is the value' do
+        VariableType::CodeListEntry.new('14').to_s.should == '14'
+      end
+    end
+  end
+end