@starci/eslint-grammar-offset-pop 0.0.0-stage → 0.12.4

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.12.4 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.4; no rule changes beyond the version pin of the exact StarCi family lint dependency.
+
+## 0.12.3 - 2026-10-26
+
+- Added: the Offset Pop flat config, inheriting Common API checks from the exact matching Grammar lint version without copying implementations.
+- Added: package regression coverage for an inherited status-tone check and mandatory rule attachment.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+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/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @starci/eslint-grammar-offset-pop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offset Pop composes the Common renderers and types. This package inherits their checks from the exact matching `@starci/eslint-grammar-starci` release; the rule implementations and shared infrastructure have one owner. Offset Pop has no additional component API rules yet. Its visual choices belong to its DNA and packaged stylesheet.
+
+Rule ownership follows `FE-RULE-OWNERSHIP` in `knowledge/patterns/fe/index.yaml`. The family's inheritance is declared in `knowledge/grammars/offset-pop/family.yaml`; the app-shell law is `knowledge/ui/composition/app-shell.yaml`.
+
+The managed `fe/eslint.config.mjs` consumes the universal canon and the selected family:
+
+```js
+import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+import { offsetPopGrammarConfig } from "@starci/eslint-grammar-offset-pop"
+
+const hfs = loadHfs(import.meta.url)
+export default [...starciFeConfig({ hfs }), ...offsetPopGrammarConfig({ hfs })]
+```
+
+The inherited rule IDs use the `starci-grammar` prefix. `rules`, `recommended`, `ruleOwners`, `lawOwners`, `ruleDeclarations`, `why` and the default plugin expose the same authoritative objects as the matching Common contract. The package has its own canon pin and generated runtime copy and follows the Grammar version.
+
+## Migrating from @starci/eslint-canon-fe 8.x
+
+The pinned canon-fe release moved the twenty Grammar component rules (listed in the `@starci/eslint-grammar-starci`
+README and the pinned canon-fe changelog) out of the universal canon. An Offset Pop app receives them
+through this package under the `starci-grammar/` namespace with unchanged IDs, codes and severity.
+
+1. Set `sides.fe.grammar` to `offset-pop` in `hfs.json`; no family is inferred.
+2. Install this package at its canon-pins version beside `@starci/eslint-canon-fe` 9 in the app
+   root `devDependencies`; it brings the matching `@starci/eslint-grammar-starci`. `starci app check`
+   refuses canon-fe 9 without it (`FE_STACK_FAMILY_LINT_MISSING`).
+3. Compose `starciFeConfig({ hfs })` first and `offsetPopGrammarConfig({ hfs })` second (the block
+   above); `starci app sync` renders that managed `fe/eslint.config.mjs`.
+4. Rename references to the moved rules from `starci-fe/` to `starci-grammar/`.
+
+Consuming apps migrate in their own release.
+
+`npm test` runs package regression specs. Grammar and application front ends carry no specs.

package/config.mjs

@@ -0,0 +1,9 @@
+import { starciGrammarConfig } from "@starci/eslint-grammar-starci"
+
+/**
+ * Attach the inherited Common API laws for a front end selecting Offset Pop.
+ *
+ * @param {{ hfs: object }} input - The front-end HFS view from the universal canon's loadHfs.
+ * @returns {Array<object>} Family rules at error under the shared starci-grammar namespace.
+ */
+export const offsetPopGrammarConfig = ({ hfs }) => starciGrammarConfig({ hfs, family: "offset-pop" })

package/index.d.ts

@@ -0,0 +1,16 @@
+import type { starciGrammarConfig } from "@starci/eslint-grammar-starci"
+
+export {
+  default,
+  rules,
+  recommended,
+  ruleOwners,
+  lawOwners,
+  ruleDeclarations,
+  why,
+} from "@starci/eslint-grammar-starci"
+
+/** Attach the inherited Common API checks for the selected Offset Pop family. */
+export declare function offsetPopGrammarConfig(input: {
+  hfs: Parameters<typeof starciGrammarConfig>[0]["hfs"]
+}): ReturnType<typeof starciGrammarConfig>

package/index.mjs

@@ -0,0 +1,11 @@
+/** Offset Pop inherits the Common component checks from the exact matching Grammar lint release. */
+export {
+  default,
+  rules,
+  recommended,
+  ruleOwners,
+  lawOwners,
+  ruleDeclarations,
+  why,
+} from "@starci/eslint-grammar-starci"
+export { offsetPopGrammarConfig } from "./config.mjs"

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@starci/eslint-grammar-offset-pop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.12.4",
+  "description": "Offset Pop Grammar lint: the inherited Common component contract over its own visual family.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "main": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "*.mjs",
+    "*.d.ts",
+    "runtime/**",
+    "!*.spec.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9",
+    "typescript": ">=5.9"
+  },
+  "dependencies": {
+    "@starci/eslint-grammar-starci": "0.12.4"
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "8.71.0",
+    "eslint": "9.39.5",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "prepack": "node ../../hfs/prep-runtime.mjs",
+    "pretest": "node ../../hfs/prep-runtime.mjs",
+    "test": "node --test \"*.spec.mjs\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "starci",
+    "grammar",
+    "offset-pop"
+  ]
+}

package/runtime/engine/plain-object.mjs

@@ -0,0 +1,5 @@
+// plain-object.mjs — the one "is this a non-array object" predicate the runtime asks with.
+// A leaf beside digest.mjs: schema walkers, config readers and JSON consumers all mean the
+// same thing by "a mapping" - own object, never null, never an array - so they share it here.
+/** True for a non-null, non-array object. Does not check the prototype (a JSON.parse result). */
+export const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);

package/runtime/engine/runtime-root.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parseYaml} from './yaml.mjs';
+
+/**
+ * Runtime root helper. The runtime reads this source tree directly. `skillRoot` is the
+ * directory containing `package.json` (this module's parent) — the checkout, or the copy of it
+ * an install placed on the host.
+ *
+ * Every workflow, op, schema, knowledge and model contract read at runtime is an authored YAML
+ * file (or an authored JSON one where a document is stored that way). `readModuleJson` resolves a
+ * path under `skillRoot` and parses the file by its extension.
+ */
+const moduleRoot = path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+
+/** The runtime root: this source tree (or an immutable sealed payload of it). */
+export const skillRoot = moduleRoot;
+/**
+ * The StarCi Source root (the host containing .claude and .workspaces): STARCI_SOURCE_ROOT overrides it, else the directory
+ * holding this runtime checkout. Parameterized over `env`, so a spec can inject a fixture Source.
+ */
+export const starciSourceRoot = (env = process.env) => (env.STARCI_SOURCE_ROOT ? path.resolve(env.STARCI_SOURCE_ROOT) : path.dirname(skillRoot));
+
+/** Overrides the per-host state base wholesale (debug probes, spec trees); the one seam starciLocalRoot reads. */
+export const LOCAL_ROOT_ENV = 'STARCI_LOCAL_ROOT';
+/** The host-data directory of a runtime root. Git-ignored and never packed; the example fixtures under examples/.runtimes are a separate, public exception. */
+export const RUNTIME_STATE_DIR = '.runtime';
+/**
+ * <root>/.runtime. The root is the `.claude` of the host Source: the checkout, or the copy `starci runtime install` places at
+ * <app>/.claude. ~/.starci/runtime/node_modules/starci is only the CLI's download cache (it supplies the installer and hosts no
+ * state), and `starci runtime link` merely points the launcher at a root, so the state follows the code's own location.
+ */
+export const runtimeStateDir = (root = skillRoot) => path.join(root, RUNTIME_STATE_DIR);
+/**
+ * The per-host state base, the one owner of every host-state location: machine.sqlite, projects/<ledger_id>/runtime.sqlite, archive/,
+ * artifacts/ (the blob store), guards/, host-lock/ and the other process state sit under it. Default <runtime root>/.runtime;
+ * LOCAL_ROOT_ENV replaces it wholesale. Nothing is read from or moved out of the earlier %LOCALAPPDATA%/StarCi and ~/.starci locations.
+ */
+export const starciLocalRoot = (env = process.env, root = skillRoot) => (env[LOCAL_ROOT_ENV] ? path.resolve(env[LOCAL_ROOT_ENV]) : runtimeStateDir(root));
+
+/**
+ * Read a runtime contract document. `parts` are path segments under `skillRoot`
+ * (e.g. readModuleJson('modules', 'models', 'kinds.yaml')).
+ */
+export function readModuleJson(...parts) {
+  const rel = parts.join('/');
+  const file = path.join(skillRoot, rel);
+  if (!(file.startsWith(skillRoot) && fs.existsSync(file) && fs.statSync(file).isFile()))
+    throw new Error(`Required contract not found for ${rel} under ${skillRoot}`);
+  const text = fs.readFileSync(file, 'utf8');
+  if (/\.ya?ml$/i.test(file)) return parseYaml(text);
+  return JSON.parse(text);
+}