proteum 2.5.11 → 2.5.12

package/agents/project/CODING_STYLE.md

@@ -83,7 +83,8 @@ Write anchors in a leading block comment:
  */
 ```
 
-- `@docs` points at the feature pack that owns the file. Required on every file that default-exports `definePageRoute`, `defineController`, `defineServerRoute`, or `defineServerRoutes`. Error routes are exempt: they render a status message and carry no feature-specific rule, so requiring a pack for one would manufacture documentation. Add an anchor to an error route only when it really does carry a rule.
+- `@docs` points at the feature pack that owns the file. Required on every file that default-exports `definePageRoute`, `defineController`, `defineServerRoute`, or `defineServerRoutes`, and on every exported class extending a service base such as `Service` or `UsersManagementService`. Error routes are exempt: they render a status message and carry no feature-specific rule, so requiring a pack for one would manufacture documentation. Add an anchor to an error route only when it really does carry a rule.
+- Components are not covered automatically. A presentational primitive such as `Icon.tsx` or `Card.tsx` owns no feature, so a blanket rule would manufacture documentation for hundreds of files. Cover the component directories that do own a feature by listing them in `includeDocAnchors` when building the ESLint config, for example `['client/components/paywall/**']`.
 - `@adr` and `@fix` point at the decision record and fix note that constrain the file. Add them where the decision or the bug actually lives, not on every file in the area.
 - `@rule` states the invariant inline, in full. It is the one anchor that carries content rather than a pointer, because the rule is what an agent needs at the moment of editing. A `@rule` that only says `todo` or repeats the linked title is a defect.
 - Anchors are not a substitute for the documents. Narrative, alternatives, benchmarks and acceptance stay under `docs/**`; the anchor carries the pointer and the single-sentence rule.

package/eslint.js

@@ -460,6 +460,74 @@ const getDefinitionCalleeName = (node, definitions) => {
     return name && definitions.includes(name) ? name : null;
 };
 
+const getSuperClassName = (node) => {
+    const superClass = node?.superClass;
+    if (!superClass) return null;
+    if (superClass.type === 'Identifier') return superClass.name;
+    // `extends Service<Config, Hooks, App, object>` parses the generic call as a
+    // member or call expression depending on the parser path.
+    if (superClass.type === 'CallExpression') return getCalleePropertyName(superClass.callee);
+    if (superClass.type === 'MemberExpression') return getMemberPropertyName(superClass);
+
+    return null;
+};
+
+/**
+ * An exported class extending a Proteum service base owns business logic, so it
+ * carries the same documentation obligation as a route or controller. Matching
+ * on the base-class suffix covers both `extends Service` and app-specific bases
+ * such as `extends UsersManagementService`.
+ */
+const isServiceClass = (node, pattern) => {
+    if (node?.type !== 'ClassDeclaration') return false;
+
+    const superClassName = getSuperClassName(node);
+    return Boolean(superClassName && pattern.test(superClassName));
+};
+
+const globToRegExp = (glob) => {
+    let pattern = '';
+
+    for (let index = 0; index < glob.length; index += 1) {
+        const character = glob[index];
+
+        if (character === '*') {
+            if (glob[index + 1] === '*') {
+                // `**/` spans any number of directories; a trailing `**` spans
+                // the rest of the path, separators included.
+                if (glob[index + 2] === '/') {
+                    pattern += '(?:[^/]*\/)*';
+                    index += 2;
+                    continue;
+                }
+
+                pattern += '.*';
+                index += 1;
+                continue;
+            }
+
+            pattern += '[^/]*';
+            continue;
+        }
+
+        pattern += '.+^${}()|[]\\?'.includes(character) ? `\\${character}` : character;
+    }
+
+    return new RegExp(`(^|/)${pattern}$`);
+};
+
+const includeMatchers = new Map();
+
+const matchesIncludeGlob = (filename, includes) => {
+    if (!filename || includes.length === 0) return false;
+
+    const normalized = filename.replace(/\\/g, '/');
+    return includes.some((glob) => {
+        if (!includeMatchers.has(glob)) includeMatchers.set(glob, globToRegExp(glob));
+        return includeMatchers.get(glob).test(normalized);
+    });
+};
+
 const createRequireDocAnchorRule = () => ({
     meta: {
         type: 'suggestion',
@@ -477,7 +545,9 @@ const createRequireDocAnchorRule = () => ({
                 type: 'object',
                 properties: {
                     definitions: { type: 'array', items: { type: 'string' } },
+                    include: { type: 'array', items: { type: 'string' } },
                     requiredTags: { type: 'array', items: { enum: docAnchorTags } },
+                    serviceBasePattern: { type: 'string' },
                 },
                 additionalProperties: false,
             },
@@ -487,22 +557,52 @@ const createRequireDocAnchorRule = () => ({
         const options = context.options?.[0] || {};
         const definitions = options.definitions || defaultDocAnchorDefinitions;
         const requiredTags = options.requiredTags || ['docs'];
+        const includes = options.include || [];
+        const serviceBasePattern = new RegExp(options.serviceBasePattern || 'Service$');
+        const filename = context.filename || context.getFilename?.() || '';
+
+        let reported = false;
+
+        const reportMissing = (node, subject) => {
+            // One report per file: a service class and an include glob can both
+            // match, and repeating the same instruction adds no information.
+            if (reported) return;
+
+            const anchors = collectFileDocAnchors(context);
+            if (anchors.entries.length === 0) {
+                reported = true;
+                context.report({ node, messageId: 'missingAnchor', data: { definition: subject } });
+                return;
+            }
+
+            const missingTag = requiredTags.find((tag) => !hasDocAnchorTag(anchors, tag));
+            if (missingTag) {
+                reported = true;
+                context.report({ node, messageId: 'missingTag', data: { definition: subject, tag: missingTag } });
+            }
+        };
+
+        const checkClass = (node) => {
+            if (!isServiceClass(node, serviceBasePattern)) return;
+            reportMissing(node, getSuperClassName(node));
+        };
 
         return {
             ExportDefaultDeclaration(node) {
-                const definition = getDefinitionCalleeName(node.declaration, definitions);
-                if (!definition) return;
-
-                const anchors = collectFileDocAnchors(context);
-                if (anchors.entries.length === 0) {
-                    context.report({ node, messageId: 'missingAnchor', data: { definition } });
+                if (node.declaration?.type === 'ClassDeclaration') {
+                    checkClass(node.declaration);
                     return;
                 }
 
-                const missingTag = requiredTags.find((tag) => !hasDocAnchorTag(anchors, tag));
-                if (missingTag) {
-                    context.report({ node, messageId: 'missingTag', data: { definition, tag: missingTag } });
-                }
+                const definition = getDefinitionCalleeName(node.declaration, definitions);
+                if (definition) reportMissing(node, definition);
+            },
+            ExportNamedDeclaration(node) {
+                if (node.declaration?.type === 'ClassDeclaration') checkClass(node.declaration);
+            },
+            'Program:exit'(node) {
+                if (!matchesIncludeGlob(filename, includes)) return;
+                reportMissing(node, path.basename(filename));
             },
         };
     },
@@ -561,7 +661,7 @@ const createValidDocAnchorRule = () => ({
     },
 });
 
-const createProteumEslintConfig = ({ docAnchors = 'warn', ignores = [] } = {}) => [
+const createProteumEslintConfig = ({ docAnchors = 'warn', includeDocAnchors = [], ignores = [] } = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
     },
@@ -602,7 +702,11 @@ const createProteumEslintConfig = ({ docAnchors = 'warn', ignores = [] } = {}) =
             'proteum/no-swallowed-caught-error': 'error',
             // Missing anchors warn by default so adopting apps see the backlog
             // without a failing build; pass `docAnchors: 'error'` once backfilled.
-            'proteum/require-doc-anchor': docAnchors,
+            // Routes, controllers and service classes are covered automatically.
+            // `includeDocAnchors` opts in extra paths, which is how a project
+            // covers the feature-owning components without dragging in every
+            // presentational primitive.
+            'proteum/require-doc-anchor': [docAnchors, { include: includeDocAnchors }],
             // A stale anchor is always an error: it only fires on files that
             // already opted in, and a pointer to a deleted document is worse
             // than no pointer at all.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.11",
+	"version": "2.5.12",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/tests/eslint-rules.test.cjs

@@ -458,6 +458,89 @@ test('proteum lint requires a doc anchor on every Proteum definition kind', () =
     }
 });
 
+test('proteum lint requires a doc anchor on exported service classes', () => {
+    const { root } = createDocProject();
+    const serviceFile = path.join(root, 'server', 'services', 'Domains', 'search', 'index.ts');
+
+    const missing = lint(
+        `export default class DomainsSearchService extends Service<Config, {}, Application, object> {}`,
+        serviceFile,
+    );
+    assert.equal(messagesFor(missing, requireDocAnchorRuleId).length, 1);
+
+    const anchored = lint(
+        `
+            /**
+             * @docs docs/features/search
+             */
+            export default class DomainsSearchService extends Service<Config, {}, Application, object> {}
+        `,
+        serviceFile,
+    );
+    assert.equal(messagesFor(anchored, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint covers app-specific service base classes and named exports', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `export class AuthManagement extends UsersManagementService<TUser, AuthApplication, TJwtSession> {}`,
+        path.join(root, 'server', 'services', 'Users', 'Auth', 'index.ts'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint leaves non-service classes alone', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `export default class DomainCard extends React.Component {}`,
+        path.join(root, 'client', 'components', 'DomainCard.tsx'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint reports a service class only once per file', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            export class FirstService extends Service {}
+            export default class SecondService extends Service {}
+        `,
+        path.join(root, 'server', 'services', 'Two', 'index.ts'),
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint opts extra files in through include globs', () => {
+    const { root } = createDocProject();
+    const paywallFile = path.join(root, 'client', 'components', 'paywall', 'PaywallModal', 'index.tsx');
+    const iconFile = path.join(root, 'client', 'components', 'Icon.tsx');
+    const source = `const Modal = () => null;\nexport default Modal;\n`;
+    const options = { docAnchors: 'warn', includeDocAnchors: ['client/components/paywall/**'] };
+
+    assert.equal(messagesFor(lint(source, paywallFile, options), requireDocAnchorRuleId).length, 1);
+    assert.equal(messagesFor(lint(source, iconFile, options), requireDocAnchorRuleId).length, 0);
+});
+
+test('proteum lint accepts an included file once it carries an anchor', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/search
+             */
+            const Modal = () => null;
+            export default Modal;
+        `,
+        path.join(root, 'client', 'components', 'paywall', 'PaywallModal', 'index.tsx'),
+        { docAnchors: 'warn', includeDocAnchors: ['client/components/paywall/**'] },
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+});
+
 test('proteum lint does not require a doc anchor on error routes', () => {
     const { root } = createDocProject();
     const messages = lint(