Skip to content

Commit 45c1ce1

Browse files
ShMcKShMcK
committed
improved documentation and typings for tutorial & tutorials modules
1 parent 3db0e16 commit 45c1ce1

File tree

13 files changed

+128
-30
lines changed

13 files changed

+128
-30
lines changed

‎lib/modules/tutorial/reducer.js

+11-6
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,17 @@ var types_1 = require('./types');
44
var config_1 = require('./utils/config');
55
var config_paths_1 = require('./utils/config-paths');
66
exports._tutorial = {
7-
name: null,
8-
version: null,
9-
info: null,
7+
name: 'default',
8+
version: '0.1.0',
9+
info: {
10+
title: 'error',
11+
description: 'Something went wrong. Tutorial not loaded.'
12+
},
1013
pages: [],
1114
packageJson: null,
1215
config: null,
1316
};
14-
var configured = [];
17+
var configured = new Set();
1518
function tutorialReducer(t, action) {
1619
if (t === void 0) { t = exports._tutorial; }
1720
switch (action.type) {
@@ -22,10 +25,12 @@ function tutorialReducer(t, action) {
2225
var config = config_1.tutorialConfig(packageJson, dir);
2326
var coderoadJsonPath = path_1.join(packagePath, packageJson.main);
2427
var _b = require(coderoadJsonPath), info = _b.info, pages = _b.pages;
25-
if (configured.indexOf(name_1) === -1) {
28+
if (configured.has(name_1)) {
2629
pages = config_paths_1.default(dir, name_1, config, pages || []);
2730
}
28-
configured.push(name_1);
31+
else {
32+
configured.add(name_1);
33+
}
2934
return {
3035
name: packageJson.name,
3136
version: version,

‎lib/modules/tutorial/utils/config-paths.js

+4
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,16 @@ function configPaths(dir, name, config, pages) {
2222
page.tasks = [];
2323
}
2424
page.tasks.map(function (task) {
25+
if (!task.tests) {
26+
return task;
27+
}
2528
task.tests = task.tests.map(function (testPath) {
2629
if (typeof testPath === 'string') {
2730
return configTestString(dir, name, config, testPath);
2831
}
2932
else {
3033
console.error('Invalid task test', testPath);
34+
return 'ERROR';
3135
}
3236
});
3337
return task;

‎lib/modules/tutorial/utils/config.js

+2-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ var config_runner_1 = require('./config-runner');
55
function tutorialConfig(tutorialPj, dir) {
66
var config = tutorialPj.config, name = tutorialPj.name;
77
var repo = config_repo_1.configRepo(tutorialPj.repo);
8-
var tutorialDir = path_1.join(dir, 'node_modules', name, config.dir);
98
var runner = config.runner;
109
var runnerOptions = config.runnerOptions || {};
1110
var configEdit = tutorialPj.config.edit;
@@ -14,12 +13,12 @@ function tutorialConfig(tutorialPj, dir) {
1413
console.log('Error loading test runner', getRunner);
1514
}
1615
return {
17-
dir: tutorialDir,
16+
dir: path_1.join(dir, 'node_modules', name, config.dir),
1817
runner: runner,
1918
runnerOptions: runnerOptions,
2019
run: getRunner.run,
2120
load: getRunner.load,
22-
testSuffix: configTestSuffix(config.testSuffix),
21+
testSuffix: configTestSuffix(config.testSuffix || 'js'),
2322
issuesPath: config_repo_1.configIssuesPath(tutorialPj.bugs),
2423
repo: repo,
2524
edit: !!repo && configEdit || false,

‎src/modules/tutorial/reducer.test.ts

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
/// <reference path="../../typings/globals/jest/index.d.ts" />
2+
13
import reducer, { _tutorial } from './reducer';
24

35
describe('tutorial reducer', () => {

‎src/modules/tutorial/reducer.ts

+10-6
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,18 @@ import { tutorialConfig } from './utils/config';
55
import configPaths from './utils/config-paths';
66

77
export const _tutorial: CR.Tutorial = {
8-
name: null,
9-
version: null,
10-
info: null,
8+
name: 'default',
9+
version: '0.1.0',
10+
info: {
11+
title: 'error',
12+
description: 'Something went wrong. Tutorial not loaded.'
13+
},
1114
pages: [],
1215
packageJson: null,
1316
config: null,
1417
};
1518

16-
const configured = [];
19+
const configured = new Set();
1720

1821
export default function tutorialReducer(
1922
t = _tutorial, action: Action
@@ -32,10 +35,11 @@ export default function tutorialReducer(
3235
let {info, pages} = require(coderoadJsonPath);
3336

3437
// configure test paths to absolute paths. Only once.
35-
if (configured.indexOf(name) === -1) {
38+
if (configured.has(name)) {
3639
pages = configPaths(dir, name, config, pages || []);
40+
} else {
41+
configured.add(name);
3742
}
38-
configured.push(name);
3943

4044
// return tutorial (info, pages) & tutorial package.json
4145
return {

‎src/modules/tutorial/utils/config-paths.ts

+20-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@ import {join} from 'path';
22

33
import {isWindows} from './system';
44

5+
/**
6+
* set paths to tests as absolute paths
7+
* @param {string} dir
8+
* @param {string} name
9+
* @param {Tutorial.Config} config
10+
* @param {string} testPath
11+
* @returns string
12+
*/
513
function configTestString(
614
dir: string, name: string, config: Tutorial.Config, testPath: string
715
): string {
@@ -25,7 +33,14 @@ function configTestString(
2533

2634
return testPath;
2735
}
28-
36+
/**
37+
* loops over task tests and set paths to absolute paths
38+
* @param {string} dir
39+
* @param {string} name
40+
* @param {Tutorial.Config} config
41+
* @param {CR.Page[]} pages
42+
* @returns CR
43+
*/
2944
export default function configPaths(
3045
dir: string, name: string, config: Tutorial.Config, pages: CR.Page[]
3146
): CR.Page[] {
@@ -34,13 +49,17 @@ export default function configPaths(
3449
page.tasks = [];
3550
}
3651
page.tasks.map((task: CR.Task): CR.Task => {
52+
53+
if (!task.tests) { return task; }
54+
3755
// change testPaths to use absolute URLs
3856
task.tests = task.tests.map((testPath: string) => {
3957
// add unique string to tests
4058
if (typeof testPath === 'string') {
4159
return configTestString(dir, name, config, testPath);
4260
} else {
4361
console.error('Invalid task test', testPath);
62+
return 'ERROR';
4463
}
4564
});
4665
return task;

‎src/modules/tutorial/utils/config-repo.test.ts

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/// <reference path="../../../typings/globals/jest/index.d.ts" />
2+
3+
import {configRepo, configIssuesPath} from './config-repo';
4+
5+
describe('config functions:', () => {
6+
7+
it('configRepo should capture a repo name', () => {
8+
const url = 'path/to/repo';
9+
const repo = {
10+
url
11+
};
12+
expect(configRepo(repo)).toBe(url);
13+
});
14+
15+
it('configIssuesPath should capture an issues path', () => {
16+
const url = 'path/to/issues';
17+
const bugs = {
18+
url
19+
};
20+
expect(configIssuesPath(bugs)).toBe(url);
21+
});
22+
23+
});

‎src/modules/tutorial/utils/config-repo.ts

+12
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* configure repo name from package.json
3+
* possible formats include: repo: string, or repo: { url: string }
4+
* @param {{url:string}} repo?
5+
* @returns string
6+
*/
17
export function configRepo(repo?: { url: string }): string|null {
28
if (repo && repo.url) {
39
let url: string = repo.url;
@@ -9,6 +15,12 @@ export function configRepo(repo?: { url: string }): string|null {
915
return null;
1016
}
1117

18+
/**
19+
* configure Github issues path from package.json
20+
* possible formats include bugs: { url: string }
21+
* @param {{url:string}} bugs?
22+
* @returns string
23+
*/
1224
export function configIssuesPath(bugs?: { url: string }): string|null {
1325
return bugs && bugs.url ? bugs.url : null;
1426
}

‎src/modules/tutorial/utils/config-runner.ts

+9-2
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
11
import {join} from 'path';
2-
32
import {isWindows} from './system';
43
import fileExists from 'node-file-exists';
54

5+
/**
6+
* sets tutorial runner (load & run)
7+
* @param {string} name
8+
* @param {string} runner
9+
* @param {string} dir
10+
*/
611
export default function configRunner(name: string, runner: string, dir: string): { run: () => any, load: () => any } {
7-
// test runner dir
12+
13+
// flat dep in NPM 3
814
let flatDep = join(
915
dir, 'node_modules', runner, 'package.json'
1016
);
17+
// tree dep occurs in NPM 2 & when using npm link
1118
let treeDep = join(
1219
dir, 'node_modules', name, 'node_modules', runner, 'package.json'
1320
);

‎src/modules/tutorial/utils/config.ts

+14-3
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,18 @@ import configRunner from './config-runner';
55
import {isWindows} from './system';
66
import fileExists from 'node-file-exists';
77

8+
/**
9+
* capture configuration variables
10+
* @param {PackageJson} tutorialPj tutorial package.json
11+
* @param {string} dir use directory
12+
* @returns Tutorial.Config
13+
*/
814
export function tutorialConfig(
915
tutorialPj: PackageJson, dir: string
1016
): Tutorial.Config {
1117
// package.json: name, config
1218
const {config, name} = tutorialPj;
1319
const repo = configRepo(tutorialPj.repo);
14-
const tutorialDir: string = join(dir, 'node_modules', name, config.dir);
1520
const runner: string = config.runner;
1621
const runnerOptions: Object = config.runnerOptions || {};
1722
const configEdit = tutorialPj.config.edit;
@@ -23,18 +28,24 @@ export function tutorialConfig(
2328
}
2429

2530
return {
26-
dir: tutorialDir,
31+
dir: join(dir, 'node_modules', name, config.dir),
2732
runner,
2833
runnerOptions,
2934
run: getRunner.run,
3035
load: getRunner.load,
31-
testSuffix: configTestSuffix(config.testSuffix),
36+
testSuffix: configTestSuffix(config.testSuffix || 'js'),
3237
issuesPath: configIssuesPath(tutorialPj.bugs),
3338
repo,
3439
edit: !!repo && configEdit || false,
3540
};
3641
}
3742

43+
/**
44+
* add test suffix to the end of files
45+
* example: '.js' -> '.js'
46+
* example: 'js' -> '.js'
47+
* @param {string} suffix
48+
*/
3849
function configTestSuffix(suffix: string) {
3950
return suffix.length && suffix[0] === '.' ? suffix : '.' + suffix || null;
4051
}

‎src/modules/tutorials/reducer.ts

+12
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,18 @@
22
import {TUTORIALS_FIND} from './types';
33
import {tutorials} from 'coderoad-cli';
44

5+
/**
6+
* tutorial reducer
7+
* loads list of installed tutorials in
8+
* package.json && node_modules
9+
*
10+
* tutorials must include a package.json file
11+
* with a "main" key pointing at the "coderoad.json" file
12+
*
13+
* @param {} t=[]
14+
* @param {Action} action
15+
* @returns Tutorial
16+
*/
517
export default function tutorialsReducer(
618
t = [], action: Action
719
): Tutorial.Info[] {

‎src/typings/coderoad/index.d.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,11 @@ declare namespace CR {
3939

4040
interface Tutorial {
4141
name: string;
42+
version?: string;
4243
info: Tutorial.Info;
4344
pages: CR.Page[];
44-
packageJson: PackageJson;
45-
config: Tutorial.Config;
46-
version?: string;
45+
packageJson: PackageJson|null;
46+
config: Tutorial.Config|null;
4747
}
4848

4949
type PagePosition = number;

‎src/typings/tutorial/index.d.ts

+6-6
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,15 @@ declare namespace Tutorial {
1313
}
1414

1515
export interface Config {
16-
language?: string;
1716
dir: string;
17+
language?: string;
1818
runner: string;
1919
runnerOptions?: Object;
20-
run: any;
21-
load: any;
22-
testSuffix?: string;
23-
issuesPath?: string;
24-
repo?: string;
20+
run: (options) => any;
21+
load: (options) => any;
22+
testSuffix?: string|null;
23+
issuesPath?: string|null;
24+
repo?: string|null;
2525
edit?: boolean;
2626
}
2727

0 commit comments

Comments
 (0)