@study-lenses/create-package 0.1.0

package/templates/DOCS.md

@@ -0,0 +1,19 @@
+# @study-lenses/CHANGEME — Architecture & Decisions
+
+## Why this package exists
+
+TODO: one paragraph — what problem does this package solve and why does it exist as a
+separate package rather than inline code?
+
+## Architecture
+
+TODO: describe the internal pipeline or data flow. Diagrams welcome.
+
+## Key decisions
+
+TODO: explain the non-obvious choices made in this package — what was considered and why
+the current approach was chosen over alternatives.
+
+## What this package deliberately does NOT do
+
+TODO: scope boundaries. What did you intentionally leave out, and why?

package/templates/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [YEAR] [NAME]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/README.md

@@ -0,0 +1,89 @@
+# @study-lenses/CHANGEME
+
+[![npm version](https://img.shields.io/npm/v/@study-lenses/CHANGEME.svg)](https://www.npmjs.com/package/@study-lenses/CHANGEME)
+[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+> TODO: One sentence — what does this package do and who is it for?
+
+## Pedagogical Purpose
+
+<!-- What role does this package play in the Study Lenses learning ecosystem?        -->
+<!-- Is it neutral infrastructure (provides data, makes no pedagogical decisions)?   -->
+<!-- Or does it implement a specific pedagogical approach? If so, which one and why? -->
+<!-- See embody's README §Design Principles for a worked example.                    -->
+
+TODO: describe the package's educational function. Choose one framing (delete the other):
+
+**Neutral infrastructure:** This package provides `[X]` for educational tool developers.
+It makes no pedagogical decisions — those belong in the tools that consume it.
+
+**Pedagogically opinionated:** This package implements `[approach/theory]` because
+`[rationale]`. It is intended to be used as `[context]`.
+
+## Who Is This For
+
+<!-- Study Lenses packages typically serve one or more of these three audiences.      -->
+<!-- Delete tiers that don't apply. Adapt descriptions to your specific package.      -->
+
+**Primary — Educational tool developers:** Building Study Lenses, custom analysis tools,
+LMS integrations, or other learning environments on top of this package.
+
+**Secondary — CS instructors:** Using this package directly to build course-specific
+tools, debugging aids, or assessment instruments.
+
+**Tertiary — CER researchers:** Using this package for data collection, intervention
+measurement, or misconception detection across student populations.
+
+## Install
+
+```bash
+npm install @study-lenses/CHANGEME
+```
+
+## Quick Start
+
+```typescript
+// TODO: Simplest possible usage — one import, one call, one meaningful output
+import { ... } from '@study-lenses/CHANGEME';
+
+const result = ...;
+console.log(result);
+```
+
+## Design Principles
+
+<!-- What does this package do, and — just as importantly — what does it NOT do?     -->
+<!-- The infrastructure/intelligence boundary is central to Study Lenses design:     -->
+<!--   infrastructure packages provide raw data / capabilities                       -->
+<!--   tool packages interpret that data and make pedagogical decisions               -->
+
+### What this package provides
+
+TODO
+
+### What this package does NOT do
+
+TODO
+
+## API Reference
+
+Generated from TSDoc comments in source. Run `npm run docs` locally, or see the
+[hosted API docs](https://OWNER.github.io/REPO/).
+
+## Architecture
+
+<!-- Contributor-facing. Describe the internal pipeline or data flow.               -->
+<!-- Pipeline diagrams belong here. Detailed conventions are in DEV.md.             -->
+
+TODO: brief description of the internal pipeline or data flow.
+
+See [DEV.md](./DEV.md) for full architecture, conventions, and the TDD workflow.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [DEV.md](./DEV.md).
+
+## License
+
+MIT © [YEAR] [NAME]

package/templates/eslint.config.js

@@ -0,0 +1,308 @@
+import tseslint from 'typescript-eslint';
+import eslintPluginBoundaries from 'eslint-plugin-boundaries';
+import eslintPluginImport from 'eslint-plugin-import';
+import eslintPluginFunctional from 'eslint-plugin-functional';
+import eslintPluginUnicorn from 'eslint-plugin-unicorn';
+import eslintPluginSonarJS from 'eslint-plugin-sonarjs';
+import eslintPluginSecurity from 'eslint-plugin-security';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+  // --- Global ignores ---
+  {
+    ignores: [
+      'dist/',
+      'node_modules/',
+      '**/*.d.ts',
+      'docs/', // TypeDoc-generated, not linted
+    ],
+  },
+
+  // --- Base TypeScript configs ---
+  ...tseslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+
+  // --- Prettier (must come after other configs to override formatting rules) ---
+  eslintConfigPrettier,
+
+  // --- All source files ---
+  {
+    files: ['src/**/*.ts'],
+    plugins: {
+      boundaries: eslintPluginBoundaries,
+      import: eslintPluginImport,
+      functional: eslintPluginFunctional,
+      unicorn: eslintPluginUnicorn,
+      sonarjs: eslintPluginSonarJS,
+      security: eslintPluginSecurity,
+    },
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.lint.json',
+      },
+    },
+    settings: {
+      // --- TypeScript import resolution (required for boundaries plugin) ---
+      'import/resolver': {
+        typescript: {
+          alwaysTryTypes: true,
+        },
+      },
+      // --- Module boundaries ---
+      'boundaries/ignore': ['**/tests/**/*.ts'],
+      'boundaries/elements': [
+        { type: 'src', pattern: 'src/**', mode: 'file' },
+      ],
+    },
+    rules: {
+      // --- Module boundaries ---
+      // TODO: All src files can import from other src files. Expand elements and rules per package.
+      'boundaries/element-types': [
+        'error',
+        {
+          default: 'disallow',
+          rules: [
+            { from: 'src', allow: ['src'] },
+          ],
+        },
+      ],
+      'boundaries/no-unknown': ['error'],
+      'boundaries/no-unknown-files': ['error'],
+
+      // --- TypeScript ---
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      // `any` types: Warn during development, review in PR
+      // Acceptable uses (see DEV.md § When `any` is OK):
+      //   - Dynamic runtime values (JSON.parse, eval results)
+      //   - Untyped library boundaries
+      //   - Generic utilities (e.g. deep-clone, deep-merge)
+      //   - Test fixtures (intentionally breaking types)
+      //   - Stub implementations (temporary mock data)
+      // All `any` usage must be justified in code review.
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unsafe-assignment': 'warn',
+      '@typescript-eslint/no-unsafe-call': 'warn',
+      '@typescript-eslint/no-unsafe-member-access': 'warn',
+      '@typescript-eslint/no-unsafe-return': 'warn',
+      '@typescript-eslint/prefer-readonly': 'error',
+      '@typescript-eslint/prefer-readonly-parameter-types': 'off',
+      '@typescript-eslint/restrict-template-expressions': 'warn',
+      '@typescript-eslint/prefer-nullish-coalescing': 'off',
+      '@typescript-eslint/prefer-optional-chain': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+      '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
+      '@typescript-eslint/no-shadow': 'error',
+
+      // --- Import rules ---
+      // TypeScript handles module resolution (.js imports → .ts files)
+      // We just forbid .ts extensions which would break at runtime
+      'import/extensions': 'off',
+      'import/order': [
+        'error',
+        {
+          groups: ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
+          'newlines-between': 'always',
+          alphabetize: { order: 'asc' },
+        },
+      ],
+      'import/no-named-export': 'error',
+      'import/prefer-default-export': 'off',
+
+      // --- Functional programming (eslint-plugin-functional) ---
+      // ERRORS: Core conventions
+      'functional/no-this-expressions': 'error',
+      'functional/no-classes': 'error',
+      // WARNINGS: Encourage immutability without blocking
+      'functional/immutable-data': [
+        'warn',
+        {
+          ignoreAccessorPattern: ['module.exports'],
+        },
+      ],
+      'functional/prefer-readonly-type': 'warn',
+      // OFF: Too strict for pedagogical codebase
+      'functional/no-let': 'off',
+      'functional/no-loop-statements': 'off',
+      'functional/no-mixed-types': 'off',
+
+      // --- Naming and style ---
+      'func-names': ['error', 'always'],
+      'unicorn/filename-case': ['error', { case: 'kebabCase' }],
+
+      // --- General rules ---
+      'no-console': 'off',
+      'no-debugger': 'error',
+      'prefer-const': 'error',
+      'no-var': 'error',
+      'object-shorthand': 'error',
+      'prefer-template': 'error',
+      'no-param-reassign': 'error',
+      'no-shadow': 'off',
+      'prefer-destructuring': [
+        'error',
+        {
+          array: false,
+          object: true,
+        },
+      ],
+      'no-invalid-this': 'error',
+      'arrow-body-style': ['error', 'never'],
+
+      // --- Unicorn (recommended + additions) ---
+      ...eslintPluginUnicorn.configs.recommended.rules,
+      'unicorn/consistent-destructuring': 'error',
+      'unicorn/prefer-switch': 'off', // Conflicts with switch ban
+      'unicorn/switch-case-braces': 'off', // Conflicts with switch ban
+      'unicorn/prefer-ternary': 'off',
+      'prevent-abbreviations': 'off',
+      'unicorn/no-null': 'off',
+
+      // --- SonarJS (recommended + additions + overrides) ---
+      ...eslintPluginSonarJS.configs.recommended.rules,
+      // Override levels
+      'sonarjs/no-duplicate-string': 'error',
+      'sonarjs/no-identical-functions': 'error',
+      'sonarjs/cognitive-complexity': ['warn', 15],
+      'sonarjs/prefer-object-literal': 'error',
+      // Disable conflicts/irrelevant
+      'sonarjs/prefer-immediate-return': 'off',
+      'sonarjs/max-switch-cases': 'off',
+      'sonarjs/no-small-switch': 'off',
+      'sonarjs/prefer-single-boolean-return': 'off',
+      'sonarjs/enforce-trailing-comma': 'off',
+      // Add rules not in recommended
+      'sonarjs/bool-param-default': 'error',
+      'sonarjs/destructuring-assignment-syntax': 'error',
+      'sonarjs/values-not-convertible-to-numbers': 'error',
+      'sonarjs/useless-string-operation': 'error',
+      'sonarjs/strings-comparison': 'error',
+      'sonarjs/non-number-in-arithmetic-expression': 'error',
+      'sonarjs/no-unused-function-argument': 'error',
+      'sonarjs/no-nested-incdec': 'error',
+      'sonarjs/no-incorrect-string-concat': 'error',
+      'sonarjs/no-inconsistent-returns': 'error',
+      'sonarjs/no-function-declaration-in-block': 'error',
+      'sonarjs/no-for-in-iterable': 'error',
+      'sonarjs/no-collapsible-if': 'error',
+      'sonarjs/no-built-in-override': 'error',
+      'sonarjs/nested-control-flow': 'error',
+      'sonarjs/expression-complexity': 'error',
+      'sonarjs/no-inverted-boolean-check': 'error',
+
+      // --- Naming conventions ---
+      camelcase: [
+        'error',
+        {
+          properties: 'never',
+          ignoreDestructuring: true,
+          ignoreImports: true,
+        },
+      ],
+
+      // --- Banned syntax patterns ---
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'SwitchStatement',
+          message: 'Switch statements are not allowed. Use if-else or lookup objects.',
+        },
+        {
+          selector: 'ImportDeclaration[source.value=/\\.ts$/]',
+          message: 'Do not use .ts extension in imports. Use .js for TypeScript ESM.',
+        },
+      ],
+
+      // --- Security (warn only - educational codebase) ---
+      'security/detect-object-injection': 'off',
+      'security/detect-non-literal-require': 'warn',
+      'security/detect-eval-with-expression': 'warn',
+
+      // --- LLM Guardrails (limit code bloat) ---
+      'spaced-comment': ['error', 'always', { exceptions: ['-', '=', '*', '/'] }],
+      'max-len': [
+        'error',
+        {
+          code: 100,
+          comments: Infinity, // Disable comment checking - use editor word wrap
+          ignoreUrls: true,
+          ignoreStrings: true,
+        },
+      ],
+    },
+  },
+
+  // --- Plain JS files (disable type-checked rules, no TS project) ---
+  {
+    files: ['**/*.js'],
+    ...tseslint.configs.disableTypeChecked,
+  },
+
+  // --- Public API (named exports allowed) ---
+  {
+    files: ['src/index.ts'],
+    rules: {
+      'import/no-named-export': 'off',
+    },
+  },
+
+  // --- Type definition files (named exports allowed) ---
+  {
+    files: ['**/types.ts', '**/*.types.ts', '**/types/*.ts'],
+    rules: {
+      'import/no-named-export': 'off',
+    },
+  },
+
+  // --- Test files ---
+  {
+    files: ['**/*.test.ts', '**/*.test.js', '**/tests/**/*.ts'],
+    languageOptions: {
+      globals: {
+        describe: 'readonly',
+        it: 'readonly',
+        test: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        vi: 'readonly',
+      },
+    },
+    rules: {
+      'import/no-named-export': 'off',
+      'functional/immutable-data': 'off',
+      'functional/prefer-readonly-type': 'off',
+      'arrow-body-style': 'off', // Test callbacks use standard arrow pattern
+      'sonarjs/no-duplicate-string': 'off', // Tests repeat literals for readability
+      'unicorn/consistent-function-scoping': 'off', // Arrow callbacks are idiomatic in tests
+      // Test fixtures are often loosely typed — strict safety checks not needed
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+
+  // --- Example files ---
+  {
+    files: ['examples/**/*.js'],
+    rules: {
+      'no-console': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+
+  // --- Error types (class/this allowed per JS Error convention) ---
+  {
+    files: ['src/errors/**/*.ts'],
+    rules: {
+      'functional/no-classes': 'off',
+      'functional/no-this-expressions': 'off',
+      'no-invalid-this': 'off',
+    },
+  },
+);

package/templates/gitignore

@@ -0,0 +1,70 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Build outputs
+dist/
+build/
+out/
+*.tsbuildinfo
+
+# Generated docs (regenerated by CI on push to main)
+docs/
+
+# Testing
+coverage/
+*.lcov
+.nyc_output/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Temporary files
+*.tmp
+*.temp
+.tmp/
+.temp/
+
+# OS files
+Thumbs.db
+Desktop.ini
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Planning files (local, not shipped)
+.plann/

package/templates/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@study-lenses/CHANGEME",
+  "version": "0.1.0",
+  "description": "PACKAGE_DESCRIPTION",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
+    "type-check": "tsc --noEmit",
+    "validate": "npm run lint && npm run type-check && npm run test",
+    "docs": "typedoc",
+    "prepare": "husky"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OWNER/REPO"
+  },
+  "author": "[NAME]",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/ui": "^2.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-boundaries": "^5.4.0",
+    "eslint-plugin-functional": "^9.0.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-security": "^3.0.1",
+    "eslint-plugin-sonarjs": "^3.0.6",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.0.0",
+    "prettier": "^3.0.0",
+    "ts-api-utils": "^2.4.0",
+    "typedoc": "^0.28.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^2.0.0"
+  }
+}

package/templates/src/DOCS.md

@@ -0,0 +1,16 @@
+# src — Architecture & Decisions
+
+TODO: explain the module structure — why these directories exist and how they relate.
+
+## Module boundaries
+
+The ESLint `boundaries` plugin enforces a DAG between modules. See `eslint.config.js`
+for the full dependency graph. In short:
+
+- TODO: describe boundary rules for your specific modules
+
+## Why no barrel files?
+
+Importing directly from source files (no `index.ts` re-exports except at package entry)
+keeps the dependency graph explicit and prevents accidental coupling. The `boundaries`
+plugin enforces this.

package/templates/src/README.md

@@ -0,0 +1,15 @@
+# src/
+
+TODO: one paragraph — what does this package's source do?
+
+## Structure
+
+| Module | Purpose  |
+| ------ | -------- |
+| TODO   | CHANGEME |
+
+## Conventions
+
+- One default export per file; no barrel imports
+- Types in `types.ts` per module
+- Tests in `tests/` subdirectory

package/templates/src/index.ts

@@ -0,0 +1 @@
+export default null;

package/templates/tsconfig.json

@@ -0,0 +1,57 @@
+{
+  "compilerOptions": {
+    // Language and Environment
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+
+    // Output
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": false,
+    "importHelpers": false,
+
+    // Type Checking
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "useUnknownInCatchVariables": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": false,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": false,
+
+    // Module Resolution
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false,
+
+    // Emit
+    "skipLibCheck": true,
+    "preserveConstEnums": true,
+    "preserveValueImports": false,
+    "downlevelIteration": true,
+
+    // Completeness
+    "skipDefaultLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.js", ".plann/**/*", "docs/**/*"]
+}

package/templates/tsconfig.lint.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", ".plann/**/*", "docs/**/*"]
+}