Importing modules in assessments

[martin-henz]

The current mission format allows us to select from a fixed set of libraries, such as TWO_DIM_RUNES, as in

    <DEPLOYMENT interpreter="2">
        <EXTERNAL name="TWO_DIM_RUNES">
            <SYMBOL>beside</SYMBOL>
            <SYMBOL>make_cross</SYMBOL>
            ...

These libraries are currently hard-wired into the Source Academy frontend. I suggest that we instead use JavaScript modules that we take from a folder lib in this assessments repository. More specifically, the IMPORT tag will include a relative path that is extended by the Source Academy to a full path to the master assessment repository of the Source Academy github organization.

Example:

    <DEPLOYMENT interpreter="2">
        <IMPORT module="cs1101s_1920/two_dim_runes">
            <SYMBOL>beside</SYMBOL>
            <SYMBOL>make_cross</SYMBOL>

This assessment would load the following module:

https://github.com/source-academy/assessments/tree/master/lib/cs1101s_1920/two_dim_runes.js

as if it was imported as follows:

import { beside, make_cross } from 'two_dim_runes';

assuming that the module two_dim_runes is written like this:

export function beside(x, y) {
    return ...;
}
export function make_cross(x) {
    return ...;
}

Views?

[martin-henz]

I've been discussing the documentation of the library functions with @blackening . We can generate the documentation of the libraries using tools like JSDoc. In that case, all exported functions would show up in the document, regardless of what functions the mission author decides to import. In other words, there may be functions in the module documentation that are not actually imported by the author of the mission. So perhaps we need to insist that all functions that are exported by a module are also imported in the mission? In that case, maybe we should not require that the author of the mission lists the imported functions using <SYMBOL> tags, and instead import all exported functions? The tag would be simply like this:

<IMPORT module="cs1101s_1920/two_dim_runes"/>

[ning-y]

The SYMBOL tag will allow assessment authors to selectively import only what they want to import. So if for any reason there is some part of an external library that the assessment author wishes to omit to the student, they can import selectively via SYMBOL tags.

Admittedly, the scenario itself is rather troublesome. Historically, selective imports hid functions because students are being asked to write those exact same functions. They could easily inspect the external library from their browser to find the answer.

Either way, I think it is also good not to crowd the global namespace with unnecessary functions.

[martin-henz]

Thanks, Ningyuan and Eldric for your input. So it seems that my original proposal is getting your approval.

FYI: With Eldric, I have discussed documentation of libraries and we think that there are ways to put together a library document using JSDoc and the functions selected in the assessment XML via <SYMBOL>.

[martin-henz]

See: https://github.com/source-academy/assessments/wiki/Assessments#import

postponed till 20/21