@openuji/speculator-lint 0.1.0 → 0.2.1

package/README.md

@@ -1,186 +1,31 @@
 # @openuji/speculator-lint
 
-Standalone linter for [Speculator](../speculator) workspace AST with configurable validation rules.
+**Developer-grade linting for technical specifications.**
 
-## Installation
+`speculator-lint` helps ensure conceptual consistency and semantic integrity in your technical specifications. It catches errors like redefinitions across spec levels, reverse dependencies, and ambiguous references.
 
-```bash
-pnpm add -D @openuji/speculator-lint
-```
-
-## Usage
+## 📖 Documentation
 
-### CLI
-
-Lint a workspace AST file:
-
-```bash
-speculator-lint workspace.json
-```
+For full documentation on available rules, configuration presets, and extensibility, please visit the [Speculator Documentation](https://speculator.pages.dev/qa/linter).
 
-With custom configuration:
+## 🚀 Quick Start
 
 ```bash
-speculator-lint workspace.json --config .speculatorlintrc.json
-```
-
-### Programmatic API
-
-```typescript
-import { readFileSync } from 'fs';
-import { SpeculatorLinter, builtInRules, recommendedConfig } from '@openuji/speculator-lint';
-
-// Load workspace AST
-const workspace = JSON.parse(readFileSync('workspace.json', 'utf-8'));
-
-// Build document levels map
-const documentLevels = new Map();
-workspace.documents.forEach((doc, index) => {
-  documentLevels.set(doc.sourcePos?.file || '', index);
-});
-
-// Create linter with built-in rules
-const linter = new SpeculatorLinter(builtInRules);
-
-// Run linter
-const result = await linter.lint({
-  workspace,
-  documentLevels,
-  config: recommendedConfig
-});
+# Install
+pnpm add -D @openuji/speculator-lint
 
-// Check results
-if (result.hasErrors) {
-  for (const diagnostic of result.diagnostics) {
-    console.error(diagnostic.message);
-  }
-}
+# Lint your workspace
+speculator-lint workspace.json
 ```
 
-## Configuration
-
-Create a `.speculatorlintrc.json` file in your project root:
+### Basic Config (`.speculatorlintrc.json`)
 
 ```json
 {
-  "extends": ["recommended"],
-  "rules": {
-    "workspace/no-redefinition": "error",
-    "workspace/no-reverse-dependency": "warning"
-  }
+  "extends": ["recommended"]
 }
 ```
 
-### Rule Configuration
-
-Rules can be configured with:
-- `"off"` - Disable the rule
-- `"error"` - Report as error
-- `"warning"` - Report as warning
-- `"info"` - Report as info
-
-### Extends
-
-Use `"extends": ["recommended"]` to enable all built-in rules with their default severities.
-
-## Built-in Rules
-
-### workspace/no-redefinition
-
-Ensures that lower-level specs do not redefine concepts from higher-level specs.
-
-**Rationale:** In a hierarchical specification system, higher-level specs define the core vocabulary. Lower-level specs should extend, not override these definitions.
-
-**Example violation:**
-
-```
-core.md (level 0): defines "User"
-extension.md (level 1): defines "User" again  ← ERROR
-```
-
-### workspace/no-reverse-dependency
-
-Ensures that higher-level specs do not depend on (reference) lower-level specs.
-
-**Rationale:** Dependencies should flow downward in the hierarchy. Higher-level specs should be self-contained and not rely on lower-level implementation details.
-
-**Example violation:**
-
-```
-core.md (level 0): references "DetailedConfig"
-extension.md (level 1): defines "DetailedConfig"  ← ERROR
-```
-
-## Creating Custom Rules
-
-You can create custom rules by implementing the `LintRule` interface:
-
-```typescript
-import type { LintRule } from '@openuji/speculator-lint';
-
-export const myCustomRule: LintRule = {
-  meta: {
-    name: 'my-custom-rule',
-    code: 'my-custom-rule',
-    severity: 'warning',
-    description: 'My custom validation rule',
-    category: 'custom'
-  },
-  
-  create(context) {
-    return {
-      // Called for each definition
-      onDefinition(entry, allEntriesForTerm) {
-        // Your validation logic
-        if (/* some condition */) {
-          context.report({
-            message: 'Issue found',
-            file: entry.sourcePos?.file,
-            sourcePos: entry.sourcePos
-          });
-        }
-      },
-      
-      // Called for each reference
-      onReference(ref, target) {
-        // Your validation logic
-      },
-      
-      // Called once per document
-      onDocument(doc) {
-        // Your validation logic
-      }
-    };
-  }
-};
-
-// Use with linter
-const linter = new SpeculatorLinter([...builtInRules, myCustomRule]);
-```
-
-## API Reference
-
-### SpeculatorLinter
-
-Main linter class.
-
-```typescript
-class SpeculatorLinter {
-  constructor(rules: LintRule[]);
-  lint(options: LintOptions): Promise<LintResult>;
-  getRules(): LintRule[];
-}
-```
-
-### Types
-
-- `LintRule` - Rule interface
-- `LintContext` - Context provided to rules
-- `LintVisitor` - Visitor pattern for AST traversal
-- `LintDiagnostic` - Diagnostic output
-- `LintResult` - Lint result with diagnostics
-- `LintConfig` - Configuration schema
-
-## License
+---
 
-MIT
+Part of the [Speculator](https://github.com/openuji/speculator) ecosystem.

package/bin/speculator-lint.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/__tests__/config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/__tests__/config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/config.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeConfig, recommendedConfig } from '../config.js';
+describe('Configuration System', () => {
+    it('should return the same config if no extends are present', () => {
+        const config = {
+            rules: {
+                'document/no-duplicate-definition': 'warning'
+            }
+        };
+        const normalized = normalizeConfig(config);
+        expect(normalized.rules).toEqual(config.rules);
+    });
+    it('should merge with recommended config when extends includes "recommended"', () => {
+        const config = {
+            extends: ['recommended'],
+            rules: {}
+        };
+        const normalized = normalizeConfig(config);
+        // Should have all recommended rules
+        expect(normalized.rules).toEqual(recommendedConfig.rules);
+    });
+    it('should allow overriding recommended rules', () => {
+        const config = {
+            extends: ['recommended'],
+            rules: {
+                'reference/no-id-reference': 'error'
+            }
+        };
+        const normalized = normalizeConfig(config);
+        // Should have the override
+        expect(normalized.rules['reference/no-id-reference']).toBe('error');
+        // Should still have other recommended rules
+        expect(normalized.rules['workspace/no-redefinition']).toBe('error');
+        expect(normalized.rules['reference/no-ambiguous-reference']).toBe('warning');
+    });
+    it('should allow disabling recommended rules', () => {
+        const config = {
+            extends: ['recommended'],
+            rules: {
+                'workspace/no-redefinition': 'off'
+            }
+        };
+        const normalized = normalizeConfig(config);
+        expect(normalized.rules['workspace/no-redefinition']).toBe('off');
+    });
+    it('should handle multiple extends if added in future (currently only "recommended")', () => {
+        const config = {
+            extends: ['recommended', 'unknown-preset'],
+            rules: {}
+        };
+        const normalized = normalizeConfig(config);
+        expect(normalized.rules).toEqual(recommendedConfig.rules);
+    });
+});
+//# sourceMappingURL=config.test.js.map

package/dist/__tests__/config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.js","sourceRoot":"","sources":["../../src/__tests__/config.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QAC/D,MAAM,MAAM,GAAe;YACvB,KAAK,EAAE;gBACH,kCAAkC,EAAE,SAAS;aAChD;SACJ,CAAC;QACF,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAChF,MAAM,MAAM,GAAe;YACvB,OAAO,EAAE,CAAC,aAAa,CAAC;YACxB,KAAK,EAAE,EAAE;SACZ,CAAC;QACF,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAE3C,oCAAoC;QACpC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACjD,MAAM,MAAM,GAAe;YACvB,OAAO,EAAE,CAAC,aAAa,CAAC;YACxB,KAAK,EAAE;gBACH,2BAA2B,EAAE,OAAO;aACvC;SACJ,CAAC;QACF,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAE3C,2BAA2B;QAC3B,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEpE,4CAA4C;QAC5C,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpE,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAChD,MAAM,MAAM,GAAe;YACvB,OAAO,EAAE,CAAC,aAAa,CAAC;YACxB,KAAK,EAAE;gBACH,2BAA2B,EAAE,KAAK;aACrC;SACJ,CAAC;QACF,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAE3C,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kFAAkF,EAAE,GAAG,EAAE;QACvF,MAAM,MAAM,GAAe;YACxB,OAAO,EAAE,CAAC,aAAa,EAAE,gBAAgB,CAAC;YAC1C,KAAK,EAAE,EAAE;SACZ,CAAC;QACF,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/__tests__/rules.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rules.test.d.ts.map

package/dist/__tests__/rules.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/rules.test.ts"],"names":[],"mappings":""}