@memberjunction/standards 0.0.0 → 6.1.0-edge.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2023 MemberJunction
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,45 +1,137 @@
 # @memberjunction/standards
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+MemberJunction's engineering standards, as runnable checks — plus the scaffolding that gets a
+repository actually enforcing them.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+```bash
+npx mj-standards adopt --ci github --declare-compliant   # set a repo up
+npx mj-standards check                                   # run what it adopted
+npx mj-standards list                                    # what exists, and this repo's stance
+```
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Inside a repo that has the MJ CLI, the same commands are `mj standards adopt` / `check` / `list`.
 
-## Purpose
+---
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/standards`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Why this package exists
 
-## What is OIDC Trusted Publishing?
+MJ has two kinds of standards and they need opposite distribution mechanisms.
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+**Judgment standards** are prose that has to be read — the guides in the MJ repo. They are
+distributed as documentation.
 
-## Setup Instructions
+**Executable standards** are the ones a machine can settle. Those are here, versioned like code,
+because copy-pasting a check script into each repo stops scaling at about five repos and guarantees
+that half of them are running a version from eight months ago.
 
-To properly configure OIDC trusted publishing for this package:
+## The property that makes it safe
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+> **Adding a standard to this package never changes an existing repository's result.**
 
-## DO NOT USE THIS PACKAGE
+Three mechanisms, together:
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+1. **Opt-in per check.** A check does nothing until a repo's `.mj-standards.json` names it.
+   Registration makes a check *available*, not active.
+2. **Version-pinned adoption.** Each check declares the MJ version it was introduced in (`Since`).
+   Each repo records the version it adopted against (`StandardsVersion`). Checks newer than that
+   are reported as available and are **not run** — upgrading this package cannot activate them.
+3. **Severity lives in the repo, not the package.** `DefaultSeverity` is what `adopt` writes for a
+   *new* adopter. Changing it here never changes a repo that has already adopted. Severity can
+   decay forward — `warn` → `error` on a major, by the repo's own choice — and never backward into
+   something already shipped.
 
-## More Information
+The result: this package can ship new standards continuously, and a repo pinned on an older MJ
+never wakes up to a red build it did not ask for. Adopting a new standard is always a visible,
+reviewable commit.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+## `.mj-standards.json`
 
----
+```jsonc
+{
+  "$schema": "./node_modules/@memberjunction/standards/schema/mj-standards.schema.json",
+  "StandardsVersion": "6.0.0",     // what this repo adopted against
+  "Checks": {
+    "ui-layers": {
+      "Severity": "error",          // off | warn | error
+      "Roots": ["packages"],
+      "Options": {
+        // Locked subtrees: an undeclared package HERE is a failure. Everywhere else it is
+        // skipped. This is the shape a real migration takes — one tree cleaned and held, the
+        // rest still being worked through.
+        "requireDeclaredIn": ["packages/Angular"]
+      }
+    }
+  }
+}
+```
+
+A check absent from `Checks` does not run. A check present but `off` does not run and is not
+nagged about — the repo has seen it and said no.
+
+## Commands
+
+### `adopt`
+
+Writes the config, and optionally a CI workflow, an npm script, and the per-package declarations.
+**Idempotent and additive**: it never lowers a severity you raised, never overwrites a CI file you
+edited, and never bumps `StandardsVersion` without `--upgrade`.
+
+| Flag | |
+|---|---|
+| `--ci github` | write `.github/workflows/mj-standards.yml` |
+| `--declare-compliant` | declare `mjUILayer` on packages that already pass |
+| `--upgrade` | enable standards newer than the recorded version, and bump it |
+| `--dry-run` | report, write nothing |
+
+**`--declare-compliant` matters more than it looks.** Without it, a fresh adoption produces a
+config that enforces nothing: every package is undeclared, so every package is skipped, and the
+repo gets a green check that means nothing.
+
+It takes the **strictest** layer each package honestly qualifies for and **never assigns `shell`**.
+`shell` checks nothing, so every package passes as `shell` — assigning it would hand a permanent
+exemption to exactly the packages that need work. (An earlier version did assign it; a two-package
+test repo caught it in the first run, with the deliberately-broken package coming back declared
+`shell` and passing.) A package that qualifies for nothing is reported, not declared.
+
+### `check`
+
+Runs the adopted standards. Exit 1 on `error` violations only; `--strict` also fails on warnings —
+the flag to turn on once a newly adopted check is clean.
+
+### `list`
+
+Every registered standard, when it was introduced, and what this repo does with it.
+
+## The standards
+
+| Id | Since | What it enforces |
+|---|---|---|
+| `ui-layers` | 6.0.0 | The four-layer UI architecture — [guide](https://github.com/MemberJunction/MJ/blob/next/guides/UI_LAYERING_GUIDE.md). Widgets may not import `@angular/router` or MJ Explorer, and may not construct a global-provider `RunView`/`Metadata`. Packages opt in with `"mjUILayer"` in their own `package.json`. |
+
+## Adding a standard
 
-**Maintained for OIDC setup purposes only**
+1. Implement `StandardCheck` in `src/checks/`.
+2. Set `Since` to the MJ version it will **ship in**. Never backdate it — that would silently
+   activate the check in repos that adopted before it existed.
+3. Register it in `src/registry.ts`.
+4. Give it a `DocsUrl`. Every failure prints it; a rule whose reasoning is one click away gets
+   followed, and one that just says "no" gets worked around.
+5. Consider shipping it at `DefaultSeverity: 'warn'` first if it is likely to have a long tail.
+
+## Design notes
+
+**No runtime dependencies.** This gets installed into client repos and run in CI; every dependency
+is one more thing that can conflict with their tree. The only non-trivial thing it needed was
+semver comparison, which is twenty lines.
+
+**Comments are stripped before matching.** MJ source documents itself heavily — a JSDoc block
+explaining "this calls `new RunView()` on the global provider" is a comment about a violation, not
+a violation. A gate that cannot tell the difference gets switched off.
+
+**Only zero-argument constructors are flagged.** `new RunView(provider)` passes a provider
+explicitly and is correct. An earlier, blunter pattern flagged it; false positives are how a gate
+loses its authority.
+
+**Reviewed exceptions** use a marker in a comment on the offending line, or the line directly
+above it — one line, so a marker cannot drift away from what it excuses. For `ui-layers` the marker
+is `mj-ui-layers-allow`.

package/bin/run.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * `mj-standards` — the standards runner, without the MJ CLI.
+ *
+ * Client and external repos should not have to install the whole MemberJunction CLI to run four
+ * checks in CI. This binary is the same code the `mj standards` commands call, exposed directly:
+ *
+ *   npx mj-standards check
+ *   npx mj-standards adopt --ci github --declare-compliant
+ *   npx mj-standards list
+ *
+ * Argument handling is deliberately minimal — anyone who wants rich flags can install the CLI.
+ */
+import { LoadConfig, HasConfig, RunStandards, FormatSummary, ExitCodeFor, Adopt, STANDARD_CHECKS, IsNewerThan } from '../dist/index.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const command = argv[0] ?? 'check';
+const repoRoot = process.cwd();
+const flag = (name) => argv.includes(`--${name}`);
+const value = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i !== -1 ? argv[i + 1] : undefined;
+};
+
+const ownVersion = JSON.parse(
+    readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
+).version;
+
+function usage() {
+    console.log(`mj-standards <check|adopt|list> [options]
+
+  check                       run the standards this repo has adopted
+    --strict                  treat warnings as errors
+    --quiet                   summary line only
+
+  adopt                       write .mj-standards.json and optional scaffolding
+    --ci github               also write a GitHub Actions workflow
+    --declare-compliant       declare mjUILayer on packages that already pass
+    --upgrade                 enable standards newer than the repo's recorded version
+    --dry-run                 report, write nothing
+
+  list                        every standard, and this repo's stance on each`);
+}
+
+if (flag('help') || command === 'help') {
+    usage();
+    process.exit(0);
+}
+
+if (command === 'check') {
+    if (!HasConfig(repoRoot)) {
+        console.error('No .mj-standards.json here. Run `npx mj-standards adopt` first.');
+        process.exit(2);
+    }
+    const config = LoadConfig(repoRoot);
+    const summary = await RunStandards(repoRoot, config);
+    if (!flag('quiet')) console.log(FormatSummary(summary, config));
+    const failed = ExitCodeFor(summary) !== 0 || (flag('strict') && summary.WarningCount > 0);
+    process.exit(failed ? 1 : 0);
+} else if (command === 'adopt') {
+    const result = Adopt({
+        RepoRoot: repoRoot,
+        Version: value('version') ?? ownVersion,
+        Upgrade: flag('upgrade'),
+        DryRun: flag('dry-run'),
+        Ci: value('ci') === 'github' ? 'github' : 'none',
+        AddNpmScript: !flag('no-npm-script'),
+        DeclareCompliant: flag('declare-compliant'),
+    });
+    const icon = { created: '+', updated: '~', skipped: '·' };
+    for (const a of result.Actions) console.log(`${icon[a.Kind]} ${a.What}${a.Detail ? ` — ${a.Detail}` : ''}`);
+    console.log(flag('dry-run') ? '\nDry run — nothing was written.' : `\nAdopted at StandardsVersion ${result.Config.StandardsVersion}.`);
+} else if (command === 'list') {
+    const config = HasConfig(repoRoot) ? LoadConfig(repoRoot) : null;
+    for (const check of STANDARD_CHECKS) {
+        const entry = config?.Checks[check.Id];
+        const stance = !config
+            ? 'not adopted'
+            : entry
+              ? entry.Severity
+              : IsNewerThan(check.Since, config.StandardsVersion)
+                ? `available (added in ${check.Since}, after this repo adopted)`
+                : 'available, not adopted';
+        console.log(`${check.Id}  [${stance}]  since ${check.Since}\n    ${check.Title}\n`);
+    }
+} else {
+    usage();
+    process.exit(2);
+}

package/dist/checks/ui-layers.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview The UI layering standard.
+ *
+ * Enforces the boundaries in the MJ repo's `guides/UI_LAYERING_GUIDE.md`:
+ *
+ *   runtime  (L0)      pure TS — no Angular at all
+ *   widgets  (L1+L2)   framework-clean Angular — no Router, no Explorer, no global provider
+ *   surface  (L3)      Explorer surfaces — NavigationService only, never Router
+ *   shell              the navigation layer ITSELF — the documented Router exception
+ *
+ * A package opts in by declaring `"mjUILayer"` in its own package.json. A package without the
+ * field is skipped, unless `requireDeclared` is on — see the option's docs for why that matters.
+ *
+ * @module @memberjunction/standards
+ */
+import type { StandardCheck } from '../types.js';
+/** The layers a package can declare. */
+export type UILayer = 'runtime' | 'widgets' | 'surface' | 'shell';
+/**
+ * Blank out `//` and block comments, preserving every newline so line numbers still line up.
+ *
+ * Necessary because MJ source documents itself heavily: a JSDoc block explaining "this calls
+ * `new RunView()` on the global provider" is a comment about a violation, not a violation, and a
+ * gate that cannot tell the difference gets switched off. String literals are left alone — the
+ * banned constructs do not plausibly appear in one.
+ */
+export declare function StripComments(source: string): string;
+/** One import/export-from occurrence. */
+export interface ImportRecord {
+    Specifier: string;
+    Names: string[];
+    Line: number;
+}
+/**
+ * Extract every import/export-from specifier with the names it binds and its 1-based line.
+ *
+ * Import-aware rather than grep-based: matching the bare word `Router` anywhere produces false
+ * positives on `RouterLikeThing`, on comments and on strings. What matters is whether the module
+ * *binds* the symbol.
+ */
+export declare function ParseImports(source: string): ImportRecord[];
+/**
+ * Does the given 1-based line carry a reviewed-exception marker, on itself or the line above?
+ *
+ * The preceding line counts because a real exception deserves a sentence of explanation and a
+ * trailing comment long enough to hold one is unreadable. Only ONE line above — a wider window
+ * would let a marker drift away from the thing it excuses.
+ */
+export declare function IsAllowed(lines: string[], lineNumber: number): boolean;
+/** The registered UI layering standard. */
+export declare const UILayersCheck: StandardCheck;
+/** A package that has not yet declared a layer, and whether it would pass if it did. */
+export interface UndeclaredPackage {
+    /** Absolute directory. */
+    Dir: string;
+    Name: string;
+    /**
+     * Layers this package could honestly claim, strictest-first, never including `shell`.
+     * Empty means it needs work before it can be declared at all.
+     */
+    WouldPassAs: UILayer[];
+}
+/**
+ * Find packages with no `mjUILayer` and work out which layers they could honestly claim.
+ *
+ * This is what lets `mj standards adopt` declare the already-compliant packages instead of leaving
+ * a repo with a config that enforces nothing. It answers the question by **running the rules**
+ * against a hypothetical layer, not by editing anything — probing by writing a field to
+ * package.json and reverting it would be a data-loss bug waiting for an interrupted process.
+ *
+ * `WouldPassAs` is ordered strictest-first and never contains `shell`, so a caller taking
+ * `WouldPassAs[0]` gets the most informative honest label, and a package that passes nothing comes
+ * back with an empty array — "needs work", not "call it shell".
+ */
+export declare function ProbeUndeclaredPackages(repoRoot: string, roots: string[]): UndeclaredPackage[];
+/** Write `mjUILayer` into a package's manifest, preserving formatting as best as JSON allows. */
+export declare function DeclareLayer(packageDir: string, layer: UILayer): void;
+//# sourceMappingURL=ui-layers.d.ts.map

package/dist/checks/ui-layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-layers.d.ts","sourceRoot":"","sources":["../../src/checks/ui-layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAA6B,aAAa,EAAa,MAAM,aAAa,CAAC;AAEvF,wCAAwC;AACxC,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AA6ElE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqBpD;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAoB3D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAItE;AAiID,2CAA2C;AAC3C,eAAO,MAAM,aAAa,EAAE,aA2F3B,CAAC;AAMF,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAC9B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,WAAW,EAAE,OAAO,EAAE,CAAC;CAC1B;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAa9F;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAKrE"}