Merge pull request #175 from Kashoo/issue-174-reorganize

Issue 174: Reorganization of source code

CHANGELOG.md

@@ -5,14 +5,14 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 ### Added
 - [#146](https://github.com/Kashoo/synctos/issues/146): Underscore.js support
-- [#123](https://github.com/Kashoo/synctos/issues/123): Specify sync-function-loader.js as the main package file
 - [#110](https://github.com/Kashoo/synctos/issues/110): Item constraint that requires an exact value match
 - [#108](https://github.com/Kashoo/synctos/issues/108): Finer grained control over whether null and missing values are accepted
 - [#127](https://github.com/Kashoo/synctos/issues/127): Immutable constraints that treat null and missing values as different
 - [#128](https://github.com/Kashoo/synctos/issues/128): Equality constraint that treats null and missing values as different
 
 ### Changed
 - [#118](https://github.com/Kashoo/synctos/issues/118): Embed indent.js as a static dependency
+- [#174](https://github.com/Kashoo/synctos/issues/174): Reorganize project source structure
 
 ## [1.9.4] - 2018-01-04
 

CONTRIBUTING.md

@@ -32,7 +32,12 @@ Issue #100: Allow test-helper module to initialize from document definitions
 
 ### Testing
 
-Every change should include comprehensive test cases defined in the `test` directory using the [Chai](http://chaijs.com/) assertion library's [expect](http://chaijs.com/api/bdd/) assertion style. Tests are executed by the [Mocha](http://mochajs.org/) test runner. Be sure to make use of the built-in test-helper module to simplify test cases wherever possible. See the synctos [Testing](https://github.com/Kashoo/synctos/blob/master/README.md#testing) documentation for more info.
+Every change should include comprehensive test cases. There are two different categories for specifications/tests in the project:
+
+- Document definition configuration: Specifications for configuration elements that are defined in the `templates` directory are stored in the `test` directory. Document definitions that are to be referenced in such test cases should be stored in the `test/resources` directory. For example, the specifications for the `mustEqual` constraint are stored at `test/must-equal.spec.js` and the corresponding test document definitions are stored at `test/resources/must-equal-doc-definitions.js`. Be sure to make use of the built-in test-helper module to simplify test cases wherever possible. See the synctos [Testing](https://github.com/Kashoo/synctos/blob/master/README.md#testing) documentation for more info.
+- Node.js supporting code: Specifications for Node.js code that is defined in the `src` directory are stored alongside the corresponding source code files in the `src` directory. Except in special cases, the specifications file's name should match that of the file under test. For example, the specifications for `src/sync-function-loader.js` are stored at `src/sync-function-loader.spec.js`.
+
+In either case, specification files must be denoted by the `.spec.js` filename suffix to be executed by the [Mocha](http://mochajs.org/) test runner. Test cases should use the [Chai](http://chaijs.com/) assertion library's [expect](http://chaijs.com/api/bdd/) assertion style.
 
 To execute the full test suite and lint the project's JS files with JSHint, run `npm test` from the project's root directory.
 
@@ -50,7 +55,7 @@ The project's `samples` directory contains a number of document definitions as e
 
 ### Backward compatibility
 
-The project's public API will evolve over time, but it is important to avoid changes that break the behaviour of validation types, document type definition properties, helper functions, etc. that are referenced in `README.md` and functions and variables that are defined in the test-helper and validation-error-message-formatter modules (and any others that may be introduced as public components over time). Only under special circumstances and with prior deliberation and approval from official project contributors will breaking changes be considered for inclusion.
+The project's public API will evolve over time, but it is important to avoid changes that break the behaviour of validation types, document type definition properties, helper functions, etc. that are referenced in `README.md` and functions and variables that are defined in the test-helper and validation-error-formatter modules (and any others that may be introduced as public components over time). Only under special circumstances and with prior deliberation and approval from official project contributors will breaking changes be considered for inclusion.
 
 ### Package dependencies
 

README.md

@@ -696,7 +696,7 @@ Once your testing libraries have been set up as development dependencies in your
 After that, create a new specification file in your project's `test/` directory (e.g. `test/foobar-spec.js`) and import the test helper module into the empty spec:
 
 ```
-var testHelper = require('../node_modules/synctos/src/test-helper.js');
+var testHelper = require('synctos').testHelper;
 ```
 
 Create a new `describe` block to encapsulate the forthcoming test cases and also initialize the synctos test helper before each test case using the `beforeEach` function. For example:
@@ -765,6 +765,6 @@ it('cannot create a myDocType doc when required property foo is missing', functi
 });
 ```
 
-The `testHelper.validationErrorFormatter` object in the preceding example provides a variety of functions that can be used to specify expected validation error messages. See the `src/validation-error-message-formatter.js` module in this project for documentation.
+The `testHelper.validationErrorFormatter` object in the preceding example provides a variety of functions that can be used to specify expected validation error messages. See the `src/validation-error-formatter.js` module in this project for documentation.
 
 You will find many more examples in this project's `test/` directory and in the example project [synctos-test-examples](https://github.com/OldSneerJaw/synctos-test-examples).

etc/test-helper.js

@@ -10,3 +10,4 @@ var deprecationMessage = 'The etc/test-helper.js module has been deprecated. Use
 exports.initSyncFunction = deprecate(testHelper.initSyncFunction, deprecationMessage);
 exports.initDocumentDefinitions = deprecate(testHelper.initDocumentDefinitions, deprecationMessage);
 exports.init = deprecate(testHelper.initSyncFunction, deprecationMessage);
+exports.validationErrorFormatter = require('./validation-error-message-formatter.js');

etc/validation-error-message-formatter.js

@@ -1,9 +1,9 @@
-// DEPRECATION NOTICE: This module has been deprecated in favour of src/validation-error-message-formatter.js
+// DEPRECATION NOTICE: This module has been deprecated in favour of src/validation-error-formatter.js
 
 var deprecate = require('util').deprecate;
-var errorFormatter = require('../src/validation-error-message-formatter.js');
+var errorFormatter = require('../src/validation-error-formatter.js');
 
-var deprecationMessage = 'The etc/validation-error-message-formatter.js module has been deprecated. Use src/validation-error-message-formatter.js instead.';
+var deprecationMessage = 'The etc/validation-error-message-formatter.js module has been deprecated. Use src/validation-error-formatter.js instead.';
 
 exports.allowAttachmentsViolation = deprecate(errorFormatter.allowAttachmentsViolation, deprecationMessage);
 exports.cannotDeleteDocViolation = deprecate(errorFormatter.cannotDeleteDocViolation, deprecationMessage);

package.json

@@ -1,7 +1,7 @@
 {
   "name": "synctos",
   "version": "1.9.4",
-  "main": "src/sync-function-loader.js",
+  "main": "src/index.js",
   "dependencies": {},
   "devDependencies": {
     "chai": "^4.1.2",
@@ -10,8 +10,8 @@
     "mock-require": "^3.0.1"
   },
   "scripts": {
-    "test": "etc/prepare-tests.sh && node_modules/.bin/mocha",
-    "test-report": "etc/prepare-tests.sh && node_modules/.bin/mocha -R xunit test/ > build/test-reports/synctos.xml"
+    "test": "etc/prepare-tests.sh && node_modules/.bin/mocha **/*.spec.js",
+    "test-report": "etc/prepare-tests.sh && node_modules/.bin/mocha -R xunit **/*.spec.js > build/test-reports/synctos.xml"
   },
   "license": "MIT",
   "repository": {

src/.jshintrc

@@ -0,0 +1,4 @@
+{
+  "extends": "../.jshintrc",
+  "mocha" : true
+}

test/document-definition-properties-validator-spec.js → src/document-definition-properties-validator.spec.js

@@ -1,5 +1,5 @@
 var expect = require('chai').expect;
-var docDefinitionPropertiesValidator = require('../src/document-definition-properties-validator.js');
+var docDefinitionPropertiesValidator = require('./document-definition-properties-validator.js');
 
 describe('Document definition properties validator', function() {
   var testPropertyValidators, testDocDefinition;

test/document-definitions-loader-spec.js → src/document-definitions-loader.spec.js

@@ -19,9 +19,9 @@ describe('Document definitions loader', function() {
     mockRequire('vm', vmMock);
 
     fileFragmentLoaderMock = { load: simpleMock.stub() };
-    mockRequire('../src/file-fragment-loader.js', fileFragmentLoaderMock);
+    mockRequire('./file-fragment-loader.js', fileFragmentLoaderMock);
 
-    docDefinitionsLoader = mockRequire.reRequire('../src/document-definitions-loader.js');
+    docDefinitionsLoader = mockRequire.reRequire('./document-definitions-loader.js');
   });
 
   afterEach(function() {

src/document-definitions-shell-maker.js

@@ -12,6 +12,7 @@
 exports.createShell = createShell;
 
 var fs = require('fs');
+var path = require('path');
 var vm = require('vm');
 
 function createShell(docDefinitionsString, originalFilename) {
@@ -22,7 +23,7 @@ function createShell(docDefinitionsString, originalFilename) {
 
   var shellTemplateString;
   try {
-    shellTemplateString = fs.readFileSync(__dirname + '/templates/document-definitions-shell-template.js', 'utf8').trim();
+    shellTemplateString = fs.readFileSync(path.resolve(__dirname, '../templates/document-definitions-shell-template.js'), 'utf8').trim();
   } catch (ex) {
     console.log('ERROR: Unable to read the document definitions shell template: ' + ex);
 

test/document-definitions-shell-maker-spec.js → src/document-definitions-shell-maker.spec.js

@@ -14,7 +14,7 @@ describe('Document definitions shell maker', function() {
     vmMock = { runInThisContext: simpleMock.stub() };
     mockRequire('vm', vmMock);
 
-    environmentShellMaker = mockRequire.reRequire('../src/document-definitions-shell-maker.js');
+    environmentShellMaker = mockRequire.reRequire('./document-definitions-shell-maker.js');
   });
 
   afterEach(function() {
@@ -36,7 +36,7 @@ describe('Document definitions shell maker', function() {
     expect(result).to.eql(expectedResult);
 
     expect(fsMock.readFileSync.callCount).to.equal(1);
-    expect(fsMock.readFileSync.calls[0].args).to.eql([ path.resolve(__dirname, '../src/templates/document-definitions-shell-template.js'), 'utf8' ]);
+    expect(fsMock.readFileSync.calls[0].args).to.eql([ path.resolve(__dirname, '../templates/document-definitions-shell-template.js'), 'utf8' ]);
 
     expect(vmMock.runInThisContext.callCount).to.equal(1);
     expect(vmMock.runInThisContext.calls[0].args).to.eql([

test/document-definitions-validator-advanced-spec.js → src/document-definitions-validator-advanced.spec.js

@@ -96,9 +96,9 @@ describe('Document definitions advanced properties validator:', function() {
 
     propertiesValidatorMock = { validate: simpleMock.stub() };
     propertiesValidatorMock.validate.returnWith([ ]);
-    mockRequire('../src/document-definition-properties-validator.js', propertiesValidatorMock);
+    mockRequire('./document-definition-properties-validator.js', propertiesValidatorMock);
 
-    docDefinitionsValidator = mockRequire.reRequire('../src/document-definitions-validator.js');
+    docDefinitionsValidator = mockRequire.reRequire('./document-definitions-validator.js');
   });
 
   afterEach(function() {

test/document-definitions-validator-essentials-spec.js → src/document-definitions-validator-essentials.spec.js

@@ -43,9 +43,9 @@ describe('Document definitions essential properties validator:', function() {
 
     propertiesValidatorMock = { validate: simpleMock.stub() };
     propertiesValidatorMock.validate.returnWith([ ]);
-    mockRequire('../src/document-definition-properties-validator.js', propertiesValidatorMock);
+    mockRequire('./document-definition-properties-validator.js', propertiesValidatorMock);
 
-    docDefinitionsValidator = mockRequire.reRequire('../src/document-definitions-validator.js');
+    docDefinitionsValidator = mockRequire.reRequire('./document-definitions-validator.js');
   });
 
   afterEach(function() {

test/file-fragment-loader-spec.js → src/file-fragment-loader.spec.js

@@ -9,7 +9,7 @@ describe('File fragment loader', function() {
     // Mock out the "require" calls in the module under test
     fsMock = { readFileSync: simpleMock.stub() };
     mockRequire('fs', fsMock);
-    fileFragmentLoader = mockRequire.reRequire('../src/file-fragment-loader.js');
+    fileFragmentLoader = mockRequire.reRequire('./file-fragment-loader.js');
   });
 
   afterEach(function() {

src/index.js

@@ -0,0 +1,16 @@
+// This module comprises the public API for synctos.
+
+/**
+ * The sync-function-loader module. Reads sync functions from files.
+ */
+exports.syncFunctionLoader = require('./sync-function-loader.js');
+
+/**
+ * The test-helper module. Provides a number of conveniences to test the behaviour of document definitions.
+ */
+exports.testHelper = require('./test-helper.js');
+
+/**
+ * The validation-error-formatter module. Formats document validation error messages for use in document definition tests.
+ */
+exports.validationErrorFormatter = require('./validation-error-formatter.js');

src/index.spec.js

@@ -0,0 +1,10 @@
+var expect = require('chai').expect;
+var index = require('./index');
+
+describe('Main package module', function() {
+  it('exposes the public API', function() {
+    expect(index.syncFunctionLoader).to.equal(require('./sync-function-loader'));
+    expect(index.testHelper).to.equal(require('./test-helper'));
+    expect(index.validationErrorFormatter).to.equal(require('./validation-error-formatter'));
+  });
+});

src/sync-function-loader.js

@@ -14,7 +14,7 @@ var docDefinitionsLoader = require('./document-definitions-loader.js');
 var fileFragmentLoader = require('./file-fragment-loader.js');
 
 function loadFromFile(docDefinitionsFile) {
-  var syncFuncTemplateDir = path.resolve(__dirname, 'templates');
+  var syncFuncTemplateDir = path.resolve(__dirname, '../templates');
 
   var syncFuncTemplatePath = path.resolve(syncFuncTemplateDir, 'sync-function-template.js');
   var syncFuncTemplate;

test/sync-function-loader-spec.js → src/sync-function-loader.spec.js

@@ -7,7 +7,7 @@ describe('Sync function loader', function() {
   var syncFunctionLoader, fsMock, indentMock, fileFragmentLoaderMock, docDefinitionsLoaderMock;
 
   var expectedMacroName = 'importSyncFunctionFragment';
-  var syncFuncTemplateDir = path.resolve(__dirname, '../src/templates');
+  var syncFuncTemplateDir = path.resolve(__dirname, '../templates');
   var syncFuncTemplateFile = path.resolve(syncFuncTemplateDir, 'sync-function-template.js');
 
   beforeEach(function() {
@@ -19,12 +19,12 @@ describe('Sync function loader', function() {
     mockRequire('../lib/indent.js/indent.min.js', indentMock);
 
     fileFragmentLoaderMock = { load: simpleMock.stub() };
-    mockRequire('../src/file-fragment-loader.js', fileFragmentLoaderMock);
+    mockRequire('./file-fragment-loader.js', fileFragmentLoaderMock);
 
     docDefinitionsLoaderMock = { load: simpleMock.stub() };
-    mockRequire('../src/document-definitions-loader.js', docDefinitionsLoaderMock);
+    mockRequire('./document-definitions-loader.js', docDefinitionsLoaderMock);
 
-    syncFunctionLoader = mockRequire.reRequire('../src/sync-function-loader.js');
+    syncFunctionLoader = mockRequire.reRequire('./sync-function-loader.js');
   });
 
   afterEach(function() {

src/test-environment-maker.js

@@ -9,6 +9,7 @@
 exports.init = init;
 
 var fs = require('fs');
+var path = require('path');
 var vm = require('vm');
 
 function init(rawSyncFunction, syncFunctionFile) {
@@ -19,7 +20,7 @@ function init(rawSyncFunction, syncFunctionFile) {
 
   var environmentTemplate;
   try {
-    environmentTemplate = fs.readFileSync(__dirname + '/templates/test-environment-template.js', 'utf8').trim();
+    environmentTemplate = fs.readFileSync(path.resolve(__dirname, '../templates/test-environment-template.js'), 'utf8').trim();
   } catch (ex) {
     console.log('ERROR: Unable to read the test environment template: ' + ex);
 

src/test-environment-maker.spec.js

@@ -0,0 +1,65 @@
+var path = require('path');
+var expect = require('chai').expect;
+var simpleMock = require('../lib/simple-mock/index.js');
+var mockRequire = require('mock-require');
+
+describe('Test environment maker', function() {
+  var testEnvironmentMaker, fsMock, vmMock;
+
+  beforeEach(function() {
+    // Mock out the "require" calls in the module under test
+    fsMock = { readFileSync: simpleMock.stub() };
+    mockRequire('fs', fsMock);
+
+    vmMock = { runInThisContext: simpleMock.stub() };
+    mockRequire('vm', vmMock);
+
+    testEnvironmentMaker = mockRequire.reRequire('./test-environment-maker.js');
+  });
+
+  afterEach(function() {
+    // Restore "require" calls to their original behaviour after each test case
+    mockRequire.stopAll();
+  });
+
+  it('creates a test environment from the input with a filename for stack traces', function() {
+    verifyParse('my-sync-func-`1`', 'my-original-filename');
+  });
+
+  it('creates a test environment from the input but without a filename', function() {
+    verifyParse('my-sync-func-\\`2\\`');
+  });
+
+  function verifyParse(rawSyncFunction, originalFilename) {
+    var envTemplateFileContents = 'template: %SYNC_FUNC_PLACEHOLDER%';
+    fsMock.readFileSync.returnWith(envTemplateFileContents);
+
+    var expectedTestEnvString = envTemplateFileContents.replace(
+      '%SYNC_FUNC_PLACEHOLDER%',
+      function() { return rawSyncFunction.replace(/\\`/g, function() { return '`'; }); });
+
+    var expectedResult = { bar: 'foo' };
+    var mockVmEnvironment = simpleMock.stub();
+    mockVmEnvironment.returnWith(expectedResult);
+
+    vmMock.runInThisContext.returnWith(mockVmEnvironment);
+
+    var result = testEnvironmentMaker.init(rawSyncFunction, originalFilename);
+
+    expect(result).to.eql(expectedResult);
+
+    expect(fsMock.readFileSync.callCount).to.equal(1);
+    expect(fsMock.readFileSync.calls[0].args).to.eql([ path.resolve(__dirname, '../templates/test-environment-template.js'), 'utf8' ]);
+
+    expect(vmMock.runInThisContext.callCount).to.equal(1);
+    expect(vmMock.runInThisContext.calls[0].args).to.eql([
+      '(' + expectedTestEnvString + ');',
+      {
+        filename: originalFilename,
+        displayErrors: true
+      }
+    ]);
+
+    expect(mockVmEnvironment.callCount).to.equal(1);
+  }
+});

src/test-helper.js

@@ -14,9 +14,9 @@ exports.initDocumentDefinitions = initDocumentDefinitions;
 
 /**
  * An object that contains functions that are used to format expected validation error messages in specifications. Documentation can be
- * found in the "validation-error-message-formatter" module.
+ * found in the "validation-error-formatter" module.
  */
-exports.validationErrorFormatter = require('./validation-error-message-formatter.js');
+exports.validationErrorFormatter = require('./validation-error-formatter.js');
 
 /**
  * Attempts to write the specified doc and then verifies that it completed successfully with the expected channels.

src/templates/document-definitions-shell-template.js → templates/document-definitions-shell-template.js

@@ -1,4 +1,5 @@
 function(require) {
+  var _ = require('../lib/underscore/underscore-min.js');
   var simple = require('../lib/simple-mock/index.js');
 
   var doc = { };
@@ -18,6 +19,7 @@ function(require) {
   var customActionStub = simple.stub();
 
   return {
+    _: _,
     doc: doc,
     oldDoc: oldDoc,
     typeIdValidator: typeIdValidator,